langsmith 0.10.4 → 0.10.6

package/dist/run_trees.js

@@ -4,11 +4,12 @@ import { isConflictingEndpointsError, ConflictingEndpointsError, } from "./utils
 import { _LC_CONTEXT_VARIABLES_KEY, _REPLICA_TRACE_ROOTS_KEY, } from "./singletons/constants.js";
 import { getContextVar, setContextVar } from "./utils/context_vars.js";
 import { getEnvironmentVariable, getRuntimeEnvironment, } from "./utils/env.js";
-import { getDefaultProjectName } from "./utils/project.js";
 import { getLangSmithEnvironmentVariable } from "./utils/env.js";
 import { warnOnce } from "./utils/warn.js";
 import { uuid7FromTime, nonCryptographicUuid7Deterministic, } from "./utils/_uuid.js";
 import { v5 as uuidv5 } from "./utils/uuid/src/index.js";
+import { checkAddress, logUntraced, rejectConflicting, resolveFromEnv, } from "./utils/agent_addressing.js";
+import { EnvAddressError, fromWire, sameAddress, seed as addressSeed, toWire, wireKeys, } from "./address.js";
 const TIMESTAMP_LENGTH = 36;
 // DNS namespace for UUID v5 (same as Python's uuid.NAMESPACE_DNS)
 const UUID_NAMESPACE_DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
@@ -43,7 +44,31 @@ const HEADER_SAFE_REPLICA_FIELDS = new Set([
     "primary",
     "updates",
     "reroot",
+    ...wireKeys(),
 ]);
+// URL-encoded JSON of the address's wire fields.
+const LANGSMITH_ADDRESS = "langsmith-address";
+/** Pops the address wire keys off untrusted `values`; never throws. */
+function takeHeaderAddress(values) {
+    const wire = {};
+    for (const key of wireKeys()) {
+        if (key in values) {
+            wire[key] = values[key];
+            delete values[key];
+        }
+    }
+    try {
+        return {
+            named: Object.keys(wire).length > 0,
+            address: fromWire(wire),
+        };
+    }
+    catch {
+        // Values are untrusted, so not logged.
+        console.warn("Ignoring an invalid address in a `baggage` header.");
+        return { named: true };
+    }
+}
 function filterReplicaForHeaders(replica) {
     const filtered = {};
     for (const key of Object.keys(replica)) {
@@ -60,7 +85,7 @@ function filterReplicaForHeaders(replica) {
  * Baggage header information
  */
 class Baggage {
-    constructor(metadata, tags, project_name, replicas) {
+    constructor(metadata, tags, project_name, replicas, address) {
         Object.defineProperty(this, "metadata", {
             enumerable: true,
             configurable: true,
@@ -85,10 +110,17 @@ class Baggage {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "address", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.metadata = metadata;
         this.tags = tags;
         this.project_name = project_name;
         this.replicas = replicas;
+        this.address = address;
     }
     static fromHeader(value) {
         const items = value.split(",");
@@ -96,6 +128,7 @@ class Baggage {
         let tags = [];
         let project_name;
         let replicas;
+        let address;
         for (const item of items) {
             const [key, uriValue] = item.split("=");
             const value = decodeURIComponent(uriValue);
@@ -108,17 +141,36 @@ class Baggage {
             else if (key === "langsmith-project") {
                 project_name = value;
             }
+            else if (key === LANGSMITH_ADDRESS) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(value);
+                }
+                catch {
+                    parsed = undefined;
+                }
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    address = takeHeaderAddress({ ...parsed }).address;
+                }
+            }
             else if (key === "langsmith-replicas") {
                 const parsed = JSON.parse(value);
-                replicas = parsed.map((replica) => {
+                replicas = parsed.flatMap((replica) => {
                     if (Array.isArray(replica)) {
-                        return replica;
+                        return [replica];
                     }
-                    return filterReplicaForHeaders(replica);
+                    const filtered = filterReplicaForHeaders(replica);
+                    const { named, address } = takeHeaderAddress(filtered);
+                    // A project wins over an address; a replica with an invalid
+                    // address and no project is dropped.
+                    if (filtered.projectName || !named) {
+                        return [filtered];
+                    }
+                    return address ? [{ ...filtered, address }] : [];
                 });
             }
         }
-        return new Baggage(metadata, tags, project_name, replicas);
+        return new Baggage(metadata, tags, project_name, replicas, address);
     }
     toHeader() {
         const items = [];
@@ -131,6 +183,9 @@ class Baggage {
         if (this.project_name) {
             items.push(`langsmith-project=${encodeURIComponent(this.project_name)}`);
         }
+        if (this.address) {
+            items.push(`${LANGSMITH_ADDRESS}=${encodeURIComponent(JSON.stringify(toWire(this.address)))}`);
+        }
         return items.join(",");
     }
 }
@@ -158,12 +213,20 @@ export class RunTree {
             writable: true,
             value: void 0
         });
+        /** Unset for a run sent to an `address`. */
         Object.defineProperty(this, "project_name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** (beta) Set instead of `project_name` for an addressed run. */
+        Object.defineProperty(this, "address", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "parent_run", {
             enumerable: true,
             configurable: true,
@@ -338,6 +401,7 @@ export class RunTree {
             delete config.id;
         }
         Object.assign(this, { ...defaultConfig, ...config, client });
+        this._resolveAddressing(config);
         this.execution_order ??= 1;
         this.child_execution_order ??= 1;
         // Generate serialized start time for ID generation
@@ -368,6 +432,31 @@ export class RunTree {
             }
         }
     }
+    /** Falls back to the env; a bad env leaves the run untraced. */
+    _resolveAddressing(config) {
+        const address = checkAddress(config.address);
+        const project = config.project_name || undefined;
+        rejectConflicting(project, address);
+        if (project || address) {
+            this.project_name = project;
+            this.address = address;
+            return;
+        }
+        try {
+            [this.project_name, this.address] = resolveFromEnv();
+        }
+        catch (e) {
+            if (!(e instanceof EnvAddressError)) {
+                throw e;
+            }
+            if (isEnvTracingEnabled(this.tracingEnabled)) {
+                logUntraced(e);
+            }
+            this.project_name = undefined;
+            this.address = undefined;
+            this.tracingEnabled = false;
+        }
+    }
     set metadata(metadata) {
         this.extra = {
             ...this.extra,
@@ -384,7 +473,6 @@ export class RunTree {
         const start_time = Date.now();
         return {
             run_type: "chain",
-            project_name: getDefaultProjectName(),
             child_runs: [],
             api_url: getEnvironmentVariable("LANGCHAIN_ENDPOINT") ?? "http://localhost:1984",
             api_key: getEnvironmentVariable("LANGCHAIN_API_KEY"),
@@ -414,6 +502,7 @@ export class RunTree {
             ...config,
             parent_run: this,
             project_name: this.project_name,
+            address: this.address,
             replicas: childReplicas,
             client: this.client,
             tracingEnabled: this.tracingEnabled,
@@ -512,6 +601,7 @@ export class RunTree {
             inputs: run.inputs,
             outputs: run.outputs,
             session_name: run.project_name,
+            address: run.address,
             child_runs: child_runs,
             parent_run_id: parent_run_id,
             trace_id: run.trace_id,
@@ -568,16 +658,33 @@ export class RunTree {
             child._setReplicaTraceRoot(replicaKey, traceRootId);
         }
     }
+    /** A replica naming neither inherits the run tree's destination. */
+    _replicaAddressing(replica) {
+        const address = checkAddress(replica.address);
+        if (replica.projectName != null) {
+            rejectConflicting(replica.projectName, address);
+            return [replica.projectName, undefined];
+        }
+        if (address) {
+            return [undefined, address];
+        }
+        return [this.project_name, this.address];
+    }
     _remapForProject(params) {
-        const { projectName, primary, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
+        const { projectName, address, primary, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
         const baseRun = this._convertToCreate(this, runtimeEnv, excludeChildRuns);
-        // Preserve legacy behavior when `primary` is omitted.
-        if (primary === undefined && projectName === this.project_name) {
+        // Preserve legacy behavior when `primary` is omitted, unless another replica is primary.
+        if (primary === undefined &&
+            !this.replicas?.some((r) => r.primary === true) &&
+            projectName === this.project_name &&
+            sameAddress(address, this.address)) {
             return {
                 ...baseRun,
                 session_name: projectName,
+                address,
             };
         }
+        const seed = projectName ?? (address ? addressSeed(address) : undefined) ?? "agent//";
         // Apply reroot logic before ID remapping
         if (reroot) {
             if (distributedParentId) {
@@ -601,7 +708,7 @@ export class RunTree {
             // Store this run's original ID in context vars so descendants know the new trace root
             // We store the original ID (before remapping) so it can be found in dotted_order
             const replicaKey = getReplicaKey({
-                projectName,
+                projectName: seed,
                 apiUrl,
                 apiKey,
                 workspaceId,
@@ -614,7 +721,7 @@ export class RunTree {
         if (!reroot) {
             const replicaTraceRoots = getContextVar(this, _REPLICA_TRACE_ROOTS_KEY) ?? {};
             const replicaKey = getReplicaKey({
-                projectName,
+                projectName: seed,
                 apiUrl,
                 apiKey,
                 workspaceId,
@@ -649,17 +756,18 @@ export class RunTree {
             return {
                 ...baseRun,
                 session_name: projectName,
+                address,
             };
         }
         // Remap IDs for the replica using nonCryptographicUuid7Deterministic
         // This ensures consistency across runs in the same replica while
         // preserving UUID7 properties (time-ordering, monotonicity)
         const oldId = baseRun.id;
-        const newId = nonCryptographicUuid7Deterministic(oldId, projectName);
+        const newId = nonCryptographicUuid7Deterministic(oldId, seed);
         // Remap trace_id
         let newTraceId;
         if (baseRun.trace_id) {
-            newTraceId = nonCryptographicUuid7Deterministic(baseRun.trace_id, projectName);
+            newTraceId = nonCryptographicUuid7Deterministic(baseRun.trace_id, seed);
         }
         else {
             newTraceId = newId;
@@ -667,7 +775,7 @@ export class RunTree {
         // Remap parent_run_id
         let newParentId;
         if (baseRun.parent_run_id) {
-            newParentId = nonCryptographicUuid7Deterministic(baseRun.parent_run_id, projectName);
+            newParentId = nonCryptographicUuid7Deterministic(baseRun.parent_run_id, seed);
         }
         // Remap dotted_order segments
         let newDottedOrder;
@@ -676,7 +784,7 @@ export class RunTree {
             const remappedSegs = segs.map((seg) => {
                 // Extract the UUID from the segment (last TIMESTAMP_LENGTH characters)
                 const segId = seg.slice(-TIMESTAMP_LENGTH);
-                const remappedId = nonCryptographicUuid7Deterministic(segId, projectName);
+                const remappedId = nonCryptographicUuid7Deterministic(segId, seed);
                 // Replace the UUID part while keeping the timestamp prefix
                 return seg.slice(0, -TIMESTAMP_LENGTH) + remappedId;
             });
@@ -689,6 +797,7 @@ export class RunTree {
             parent_run_id: newParentId,
             dotted_order: newDottedOrder,
             session_name: projectName,
+            address,
         };
     }
     async postRun(excludeChildRuns = true) {
@@ -699,9 +808,12 @@ export class RunTree {
         try {
             const runtimeEnv = getRuntimeEnvironment();
             if (this.replicas && this.replicas.length > 0) {
-                for (const { projectName, primary, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } of this.replicas) {
+                for (const replica of this.replicas) {
+                    const { primary, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } = replica;
+                    const [projectName, address] = this._replicaAddressing(replica);
                     const runCreate = this._remapForProject({
-                        projectName: projectName ?? this.project_name,
+                        projectName,
+                        address,
                         primary,
                         runtimeEnv,
                         excludeChildRuns: true,
@@ -750,9 +862,12 @@ export class RunTree {
     async patchRun(options) {
         const excludeInputs = options?.excludeInputs ?? getExcludeInputsOnPatch();
         if (this.replicas && this.replicas.length > 0) {
-            for (const { projectName, primary, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } of this.replicas) {
+            for (const replica of this.replicas) {
+                const { primary, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } = replica;
+                const [projectName, address] = this._replicaAddressing(replica);
                 const runData = this._remapForProject({
-                    projectName: projectName ?? this.project_name,
+                    projectName,
+                    address,
                     primary,
                     runtimeEnv: undefined,
                     excludeChildRuns: true,
@@ -771,6 +886,7 @@ export class RunTree {
                     error: runData.error,
                     parent_run_id: runData.parent_run_id,
                     session_name: runData.session_name,
+                    address: runData.address,
                     reference_example_id: runData.reference_example_id,
                     end_time: runData.end_time,
                     dotted_order: runData.dotted_order,
@@ -813,6 +929,7 @@ export class RunTree {
                     tags: this.tags,
                     attachments: this.attachments,
                     session_name: this.project_name,
+                    address: this.address,
                 };
                 // Important that inputs is not a key in the run update
                 // if excluded because it will overwrite the run create if the
@@ -873,7 +990,7 @@ export class RunTree {
                 ...props,
                 client,
                 tracingEnabled,
-                project_name: projectName,
+                project_name: props.address ? undefined : projectName,
             });
         }
         const parentRunTree = new RunTree({
@@ -928,7 +1045,19 @@ export class RunTree {
             const baggage = Baggage.fromHeader(rawHeaders["baggage"]);
             config.metadata = baggage.metadata;
             config.tags = baggage.tags;
-            config.project_name = baggage.project_name;
+            if (baggage.project_name && baggage.address) {
+                console.warn("Ignoring a `baggage` header that names both a project and an address.");
+                return undefined;
+            }
+            // The header's destination outranks the caller's.
+            if (baggage.project_name) {
+                config.project_name = baggage.project_name;
+                delete config.address;
+            }
+            else if (baggage.address) {
+                config.address = baggage.address;
+                delete config.project_name;
+            }
             config.replicas = baggage.replicas;
         }
         const runTree = new RunTree(config);
@@ -939,7 +1068,7 @@ export class RunTree {
     toHeaders(headers) {
         const result = {
             "langsmith-trace": this.dotted_order,
-            baggage: new Baggage(this.extra?.metadata, this.tags, this.project_name, this.replicas).toHeader(),
+            baggage: new Baggage(this.extra?.metadata, this.tags, this.project_name, this.replicas, this.address).toHeader(),
         };
         if (headers) {
             for (const [key, value] of Object.entries(result)) {
@@ -1075,7 +1204,8 @@ function _ensureWriteReplicas(replicas) {
                     updates: replica[1],
                 };
             }
-            return replica;
+            const address = checkAddress(replica.address);
+            return address ? { ...replica, address } : replica;
         })
         : _getWriteReplicasFromEnv();
     if (ensured.filter((replica) => replica.primary === true).length > 1) {

package/dist/sandbox/access_delegation.cjs

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAccessDelegation = validateAccessDelegation;
+const errors_js_1 = require("./errors.cjs");
+/** Rejects grants the server would refuse, without the round trip. */
+function validateAccessDelegation(value) {
+    if (value.mode !== "INHERIT" && value.mode !== "EXPLICIT") {
+        throw new errors_js_1.LangSmithValidationError('accessDelegation.mode must be "INHERIT" or "EXPLICIT"', "accessDelegation");
+    }
+    const { permissions } = value;
+    if (permissions !== undefined && !Array.isArray(permissions)) {
+        throw new errors_js_1.LangSmithValidationError("accessDelegation.permissions must be an array of strings", "accessDelegation");
+    }
+    if (value.mode === "INHERIT") {
+        if (permissions !== undefined && permissions.length > 0) {
+            throw new errors_js_1.LangSmithValidationError('accessDelegation.permissions is not allowed with mode "INHERIT"', "accessDelegation");
+        }
+        return { mode: "INHERIT" };
+    }
+    if (permissions === undefined || permissions.length === 0) {
+        throw new errors_js_1.LangSmithValidationError('accessDelegation.permissions is required with mode "EXPLICIT"', "accessDelegation");
+    }
+    return { mode: "EXPLICIT", permissions: [...permissions] };
+}

package/dist/sandbox/access_delegation.d.ts

@@ -0,0 +1,15 @@
+/** How a delegation grant derives its permission set. */
+export type AccessDelegationMode = "INHERIT" | "EXPLICIT";
+/**
+ * Grant letting code inside a sandbox call the LangSmith API as the creator.
+ *
+ * `INHERIT` tracks everything the creator can do; `EXPLICIT` is capped to
+ * `permissions`. Permissions are a ceiling re-checked on every request rather
+ * than a snapshot, so access the creator loses is lost here too.
+ */
+export interface AccessDelegation {
+    mode: AccessDelegationMode;
+    permissions?: string[];
+}
+/** Rejects grants the server would refuse, without the round trip. */
+export declare function validateAccessDelegation(value: AccessDelegation): AccessDelegation;

package/dist/sandbox/access_delegation.js

@@ -0,0 +1,21 @@
+import { LangSmithValidationError } from "./errors.js";
+/** Rejects grants the server would refuse, without the round trip. */
+export function validateAccessDelegation(value) {
+    if (value.mode !== "INHERIT" && value.mode !== "EXPLICIT") {
+        throw new LangSmithValidationError('accessDelegation.mode must be "INHERIT" or "EXPLICIT"', "accessDelegation");
+    }
+    const { permissions } = value;
+    if (permissions !== undefined && !Array.isArray(permissions)) {
+        throw new LangSmithValidationError("accessDelegation.permissions must be an array of strings", "accessDelegation");
+    }
+    if (value.mode === "INHERIT") {
+        if (permissions !== undefined && permissions.length > 0) {
+            throw new LangSmithValidationError('accessDelegation.permissions is not allowed with mode "INHERIT"', "accessDelegation");
+        }
+        return { mode: "INHERIT" };
+    }
+    if (permissions === undefined || permissions.length === 0) {
+        throw new LangSmithValidationError('accessDelegation.permissions is required with mode "EXPLICIT"', "accessDelegation");
+    }
+    return { mode: "EXPLICIT", permissions: [...permissions] };
+}

package/dist/sandbox/client.cjs

@@ -4,6 +4,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxClient = void 0;
+const access_delegation_js_1 = require("./access_delegation.cjs");
+const service_url_js_1 = require("./service_url.cjs");
 const env_js_1 = require("../utils/env.cjs");
 const fetch_js_1 = require("../singletons/fetch.cjs");
 const async_caller_js_1 = require("../utils/async_caller.cjs");
@@ -407,6 +409,53 @@ class SandboxClient {
         const suffix = segments.length ? `/${segments.join("/")}` : "";
         return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
     }
+    /**
+     * Generate an authenticated URL for an HTTP service running in a sandbox.
+     *
+     * Without `access`, mints a short-lived token and returns a {@link ServiceUrl}
+     * that refreshes it as it nears expiry. With `access` set to `"restricted"`
+     * or `"workspace"` the URL is gated by LangSmith login instead and a
+     * {@link ServiceLoginUrl} is returned: no token, no expiry, browser only.
+     *
+     * A login grant is durable, so token mode is refused with 409 while one is
+     * in place, and `expiresInSeconds` does not apply to the login modes.
+     */
+    async serviceUrl(name, options) {
+        const { port, expiresInSeconds, access, signal } = options;
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new errors_js_1.LangSmithValidationError(`port must be between 1 and 65535 (got ${port})`, "port");
+        }
+        if (access !== undefined &&
+            access !== "restricted" &&
+            access !== "workspace") {
+            throw new errors_js_1.LangSmithValidationError(`access must be "restricted" or "workspace" (got ${String(access)})`, "access");
+        }
+        const loginMode = access !== undefined;
+        if (expiresInSeconds !== undefined && loginMode) {
+            throw new errors_js_1.LangSmithValidationError(`expiresInSeconds does not apply to access "${access}": a LangSmith ` +
+                "login URL carries no token and does not expire", "expiresInSeconds");
+        }
+        const url = this._boxUrl(name, "service-url");
+        const payload = { port };
+        if (!loginMode && expiresInSeconds !== undefined) {
+            payload.expires_in_seconds = expiresInSeconds;
+        }
+        if (access !== undefined) {
+            payload.access = access;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const data = await response.json();
+        if (loginMode) {
+            return new service_url_js_1.ServiceLoginUrl(data);
+        }
+        // Refresh with the token parameters only. Carrying options.signal over
+        // would tie every later refresh to the first request's lifetime, so a
+        // caller-supplied timeout signal would leave the URL unable to refresh.
+        return new service_url_js_1.ServiceUrl(data, () => this.serviceUrl(name, {
+            port,
+            expiresInSeconds,
+        }));
+    }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
             method: "POST",
@@ -424,7 +473,7 @@ class SandboxClient {
         const resolvedOptions = typeof snapshotIdOrOptions === "object" && snapshotIdOrOptions !== null
             ? snapshotIdOrOptions
             : options;
-        const { snapshotName, name, timeout = 30, waitForReady = true, idleTtlSeconds, deleteAfterStopSeconds, vCpus, memBytes, fsCapacityBytes, mountConfig, proxyConfig, } = resolvedOptions;
+        const { snapshotName, name, timeout = 30, waitForReady = true, idleTtlSeconds, deleteAfterStopSeconds, vCpus, memBytes, fsCapacityBytes, mountConfig, proxyConfig, runConfig, accessDelegation, } = resolvedOptions;
         if (snapshotId && snapshotName) {
             throw new errors_js_1.LangSmithValidationError("At most one of snapshotId or options.snapshotName may be set", "snapshotId");
         }
@@ -468,6 +517,12 @@ class SandboxClient {
         if (proxyConfig !== undefined) {
             payload.proxy_config = proxyConfig;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
+        if (accessDelegation !== undefined) {
+            payload.access_delegation = (0, access_delegation_js_1.validateAccessDelegation)(accessDelegation);
+        }
         const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
@@ -523,13 +578,14 @@ class SandboxClient {
         const options = typeof newNameOrOptions === "string"
             ? { newName: newNameOrOptions }
             : newNameOrOptions;
-        const { newName, idleTtlSeconds, deleteAfterStopSeconds, proxyConfig } = options;
+        const { newName, idleTtlSeconds, deleteAfterStopSeconds, proxyConfig, runConfig, } = options;
         (0, helpers_js_1.validateTtl)(idleTtlSeconds, "idleTtlSeconds");
         (0, helpers_js_1.validateTtl)(deleteAfterStopSeconds, "deleteAfterStopSeconds");
         if (newName === undefined &&
             idleTtlSeconds === undefined &&
             deleteAfterStopSeconds === undefined &&
-            proxyConfig === undefined) {
+            proxyConfig === undefined &&
+            runConfig === undefined) {
             return this.getSandbox(name);
         }
         const url = this._boxUrl(name);
@@ -546,6 +602,9 @@ class SandboxClient {
         if (proxyConfig !== undefined) {
             payload.proxy_config = proxyConfig;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._fetch(url, {
             method: "PATCH",
             headers: { "Content-Type": "application/json" },
@@ -730,7 +789,7 @@ class SandboxClient {
      * @returns Snapshot in "ready" status.
      */
     async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
-        const { registryId, timeout = 60, signal } = options;
+        const { registryId, runConfig, timeout = 60, signal } = options;
         const url = `${this._baseUrl}/snapshots`;
         const payload = {
             name,
@@ -740,6 +799,9 @@ class SandboxClient {
         if (registryId !== undefined) {
             payload.registry_id = registryId;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });
@@ -832,7 +894,7 @@ class SandboxClient {
      * @returns Snapshot in "ready" status.
      */
     async captureSnapshot(sandboxName, name, options = {}) {
-        const { dockerImage, fsCapacityBytes, timeout = 60, signal } = options;
+        const { dockerImage, fsCapacityBytes, runConfig, timeout = 60, signal, } = options;
         const url = this._boxUrl(sandboxName, "snapshot");
         const payload = { name };
         if (dockerImage !== undefined) {
@@ -841,6 +903,9 @@ class SandboxClient {
         if (fsCapacityBytes !== undefined) {
             payload.fs_capacity_bytes = fsCapacityBytes;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });

package/dist/sandbox/client.d.ts

@@ -1,6 +1,7 @@
 /**
  * Main SandboxClient class for interacting with the sandbox server API.
  */
+import { ServiceLoginUrl, ServiceUrl, type ServiceAccess } from "./service_url.js";
 import { Registries } from "../_openapi_client/resources/sandboxes/registries.js";
 import type { CaptureSnapshotOptions, CreateDockerfileSnapshotOptions, CreateSandboxOptions, CreateSnapshotOptions, DownloadURL, GenerateDownloadURLOptions, ListSnapshotsOptions, ResourceStatus, SandboxClientConfig, Snapshot, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, WaitForSnapshotOptions } from "./types.js";
 import { Sandbox } from "./sandbox.js";
@@ -64,6 +65,23 @@ export declare class SandboxClient {
      * ```
      */
     get registries(): Registries;
+    /**
+     * Generate an authenticated URL for an HTTP service running in a sandbox.
+     *
+     * Without `access`, mints a short-lived token and returns a {@link ServiceUrl}
+     * that refreshes it as it nears expiry. With `access` set to `"restricted"`
+     * or `"workspace"` the URL is gated by LangSmith login instead and a
+     * {@link ServiceLoginUrl} is returned: no token, no expiry, browser only.
+     *
+     * A login grant is durable, so token mode is refused with 409 while one is
+     * in place, and `expiresInSeconds` does not apply to the login modes.
+     */
+    serviceUrl(name: string, options: {
+        port: number;
+        expiresInSeconds?: number;
+        access?: ServiceAccess;
+        signal?: AbortSignal;
+    }): Promise<ServiceUrl | ServiceLoginUrl>;
     private _postJson;
     /**
      * Create a new Sandbox.