langsmith 0.10.4 → 0.10.5

package/dist/client.cjs

@@ -866,6 +866,10 @@ class Client {
             throw new Error("Trace batch concurrency must be positive.");
         }
         this.debug = config.debug ?? this.debug;
+        if (this.debug) {
+            const source = config.apiUrl != null ? "apiUrl option" : defaultConfig.apiUrlSource;
+            console.log(`LangSmith API URL ${this.apiUrl} resolved from ${source}`);
+        }
         this.fetchImplementation = config.fetchImplementation;
         // Failed trace dump configuration
         this.failedTracesDir =
@@ -952,12 +956,18 @@ class Client {
         const envWorkspaceId = (0, env_js_1.getLangSmithEnvironmentVariable)("WORKSPACE_ID");
         const envAuthSet = (0, profiles_js_1.hasValue)(envApiKey);
         const apiUrl = envApiUrl ?? profileConfig.apiUrl ?? profiles_js_1.DEFAULT_API_URL;
+        const apiUrlSource = envApiUrl != null
+            ? "LANGSMITH_ENDPOINT / LANGCHAIN_ENDPOINT environment variable"
+            : profileConfig.apiUrl != null
+                ? "profile config"
+                : "built-in default";
         const workspaceId = envWorkspaceId ?? profileConfig.workspaceId;
         const hideInputs = (0, env_js_1.getLangSmithEnvironmentVariable)("HIDE_INPUTS") === "true";
         const hideOutputs = (0, env_js_1.getLangSmithEnvironmentVariable)("HIDE_OUTPUTS") === "true";
         const hideMetadata = (0, env_js_1.getLangSmithEnvironmentVariable)("HIDE_METADATA") === "true";
         return {
             apiUrl: apiUrl,
+            apiUrlSource,
             apiKey: envApiKey,
             webUrl: undefined,
             hideInputs: hideInputs,

package/dist/client.d.ts

@@ -300,6 +300,7 @@ interface UploadCSVParams {
 }
 type DefaultClientConfig = {
     apiUrl: string;
+    apiUrlSource: string;
     apiKey?: string;
     webUrl?: string;
     hideInputs?: boolean;

package/dist/client.js

@@ -827,6 +827,10 @@ export class Client {
             throw new Error("Trace batch concurrency must be positive.");
         }
         this.debug = config.debug ?? this.debug;
+        if (this.debug) {
+            const source = config.apiUrl != null ? "apiUrl option" : defaultConfig.apiUrlSource;
+            console.log(`LangSmith API URL ${this.apiUrl} resolved from ${source}`);
+        }
         this.fetchImplementation = config.fetchImplementation;
         // Failed trace dump configuration
         this.failedTracesDir =
@@ -913,12 +917,18 @@ export class Client {
         const envWorkspaceId = getLangSmithEnvironmentVariable("WORKSPACE_ID");
         const envAuthSet = hasValue(envApiKey);
         const apiUrl = envApiUrl ?? profileConfig.apiUrl ?? DEFAULT_API_URL;
+        const apiUrlSource = envApiUrl != null
+            ? "LANGSMITH_ENDPOINT / LANGCHAIN_ENDPOINT environment variable"
+            : profileConfig.apiUrl != null
+                ? "profile config"
+                : "built-in default";
         const workspaceId = envWorkspaceId ?? profileConfig.workspaceId;
         const hideInputs = getLangSmithEnvironmentVariable("HIDE_INPUTS") === "true";
         const hideOutputs = getLangSmithEnvironmentVariable("HIDE_OUTPUTS") === "true";
         const hideMetadata = getLangSmithEnvironmentVariable("HIDE_METADATA") === "true";
         return {
             apiUrl: apiUrl,
+            apiUrlSource,
             apiKey: envApiKey,
             webUrl: undefined,
             hideInputs: hideInputs,

package/dist/evaluation/_runner.cjs

@@ -211,6 +211,12 @@ class _ExperimentManager {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_disableEvaluatorTracing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.client = args.client ?? new index_js_1.Client();
         if (!args.experiment) {
             this._experimentName = (0, _random_name_js_1.randomName)();
@@ -248,6 +254,7 @@ class _ExperimentManager {
         this._numExamples = args.numExamples;
         this._evaluatorKeys = args.evaluatorKeys;
         this._includeAttachments = args.includeAttachments;
+        this._disableEvaluatorTracing = args.disableEvaluatorTracing;
     }
     _getExperiment() {
         if (!this._experiment) {
@@ -350,6 +357,7 @@ class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async withPredictions(target, options) {
@@ -379,6 +387,7 @@ class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async withEvaluators(evaluators, options) {
@@ -406,6 +415,7 @@ class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async withSummaryEvaluators(summaryEvaluators) {
@@ -424,6 +434,7 @@ class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async *getResults() {
@@ -541,9 +552,14 @@ class _ExperimentManager {
                             : new Date(example.created_at).toISOString(),
                     },
                     client: fields.client,
-                    tracingEnabled: true,
+                    tracingEnabled: !this._disableEvaluatorTracing,
                 };
-                const evaluatorResponse = await evaluator.evaluateRun(run, example, options);
+                const rawEvaluatorResponse = await evaluator.evaluateRun(run, example, options);
+                // With tracing off there is no evaluator run for the feedback to point
+                // at, so drop the link rather than leaving it dangling.
+                const evaluatorResponse = this._disableEvaluatorTracing
+                    ? _withoutSourceRunIds(rawEvaluatorResponse)
+                    : rawEvaluatorResponse;
                 evaluationResults.results.push(...(await fields.client.logEvaluationFeedback({
                     evaluatorResponse,
                     run,
@@ -590,7 +606,10 @@ class _ExperimentManager {
             experiment: this.experimentName,
             projectId: projectId,
         }));
-        const wrappedEvaluators = await wrapSummaryEvaluators(summaryEvaluators, options);
+        const wrappedEvaluators = await wrapSummaryEvaluators(summaryEvaluators, options, 
+        // Only override when disabling. Passing `true` here would force tracing
+        // on for callers who have it switched off via the environment.
+        this._disableEvaluatorTracing ? false : undefined);
         yield async function* (runsArray) {
             const aggregateFeedback = [];
             for (const evaluator of wrappedEvaluators) {
@@ -777,6 +796,7 @@ async function _evaluate(target, fields) {
         numRepetitions: fields.numRepetitions ?? 1,
         evaluatorKeys: _collectEvaluatorKeys(standardFields.evaluators),
         includeAttachments: standardFields.includeAttachments,
+        disableEvaluatorTracing: standardFields.disableEvaluatorTracing,
     }).start();
     const targetConcurrency = standardFields.targetConcurrency ?? standardFields.maxConcurrency ?? 0;
     const evaluationConcurrency = standardFields.evaluationConcurrency ?? standardFields.maxConcurrency ?? 0;
@@ -988,7 +1008,25 @@ function _resolveData(data, options) {
     }
     return data;
 }
-async function wrapSummaryEvaluators(evaluators, optionsArray) {
+/**
+ * Strip evaluator-run links from an evaluator response.
+ *
+ * Used when evaluator tracing is disabled: no evaluator run is created, so a
+ * `sourceRunId` on the feedback would point at a run that does not exist.
+ */
+function _withoutSourceRunIds(response) {
+    if ("results" in response) {
+        return {
+            ...response,
+            results: response.results.map((result) => ({
+                ...result,
+                sourceRunId: undefined,
+            })),
+        };
+    }
+    return { ...response, sourceRunId: undefined };
+}
+async function wrapSummaryEvaluators(evaluators, optionsArray, tracingEnabled) {
     async function _wrap(evaluator) {
         const evalName = evaluator.name || "BatchEvaluator";
         const wrapperInner = (runs, examples) => {
@@ -1008,7 +1046,11 @@ async function wrapSummaryEvaluators(evaluators, optionsArray) {
                 }
                 // Otherwise use the traditional (runs, examples) signature
                 return Promise.resolve(evaluator(runs, examples));
-            }, { ...optionsArray, name: evalName });
+            }, {
+                ...optionsArray,
+                name: evalName,
+                ...(tracingEnabled === undefined ? {} : { tracingEnabled }),
+            });
             return Promise.resolve(wrapperSuperInner(`Runs[] (Length=${runs.length})`, `Examples[] (Length=${examples.length})`));
         };
         return wrapperInner;

package/dist/evaluation/_runner.d.ts

@@ -73,6 +73,7 @@ interface _ExperimentManagerArgs {
     _runsArray?: Run[];
     resultRows?: AsyncGenerator<_ExperimentResultRowWithIndex>;
     includeAttachments?: boolean;
+    disableEvaluatorTracing?: boolean;
 }
 type BaseEvaluateOptions = {
     /**
@@ -140,6 +141,16 @@ export interface EvaluateOptions extends BaseEvaluateOptions {
      * @default false
      */
     includeAttachments?: boolean;
+    /**
+     * Whether to skip tracing evaluator invocations to the `evaluators` project.
+     *
+     * When `true`, evaluators run without creating evaluator traces. Feedback is
+     * still created and attached to the experiment runs, but it won't link back
+     * to an evaluator run, which also means it can't be corrected from the UI.
+     * Tracing of the target itself is unaffected.
+     * @default false
+     */
+    disableEvaluatorTracing?: boolean;
 }
 export interface ComparativeEvaluateOptions extends BaseEvaluateOptions {
     /**
@@ -194,6 +205,7 @@ export declare class _ExperimentManager {
     _metadata: KVMap;
     _description?: string;
     _includeAttachments?: boolean;
+    _disableEvaluatorTracing?: boolean;
     get experimentName(): string;
     getExamples(): Promise<Array<Example>>;
     setExamples(examples: Example[]): void;

package/dist/evaluation/_runner.js

@@ -203,6 +203,12 @@ export class _ExperimentManager {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_disableEvaluatorTracing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.client = args.client ?? new Client();
         if (!args.experiment) {
             this._experimentName = randomName();
@@ -240,6 +246,7 @@ export class _ExperimentManager {
         this._numExamples = args.numExamples;
         this._evaluatorKeys = args.evaluatorKeys;
         this._includeAttachments = args.includeAttachments;
+        this._disableEvaluatorTracing = args.disableEvaluatorTracing;
     }
     _getExperiment() {
         if (!this._experiment) {
@@ -342,6 +349,7 @@ export class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async withPredictions(target, options) {
@@ -371,6 +379,7 @@ export class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async withEvaluators(evaluators, options) {
@@ -398,6 +407,7 @@ export class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async withSummaryEvaluators(summaryEvaluators) {
@@ -416,6 +426,7 @@ export class _ExperimentManager {
             numExamples: this._numExamples,
             evaluatorKeys: this._evaluatorKeys,
             includeAttachments: this._includeAttachments,
+            disableEvaluatorTracing: this._disableEvaluatorTracing,
         });
     }
     async *getResults() {
@@ -533,9 +544,14 @@ export class _ExperimentManager {
                             : new Date(example.created_at).toISOString(),
                     },
                     client: fields.client,
-                    tracingEnabled: true,
+                    tracingEnabled: !this._disableEvaluatorTracing,
                 };
-                const evaluatorResponse = await evaluator.evaluateRun(run, example, options);
+                const rawEvaluatorResponse = await evaluator.evaluateRun(run, example, options);
+                // With tracing off there is no evaluator run for the feedback to point
+                // at, so drop the link rather than leaving it dangling.
+                const evaluatorResponse = this._disableEvaluatorTracing
+                    ? _withoutSourceRunIds(rawEvaluatorResponse)
+                    : rawEvaluatorResponse;
                 evaluationResults.results.push(...(await fields.client.logEvaluationFeedback({
                     evaluatorResponse,
                     run,
@@ -582,7 +598,10 @@ export class _ExperimentManager {
             experiment: this.experimentName,
             projectId: projectId,
         }));
-        const wrappedEvaluators = await wrapSummaryEvaluators(summaryEvaluators, options);
+        const wrappedEvaluators = await wrapSummaryEvaluators(summaryEvaluators, options, 
+        // Only override when disabling. Passing `true` here would force tracing
+        // on for callers who have it switched off via the environment.
+        this._disableEvaluatorTracing ? false : undefined);
         yield async function* (runsArray) {
             const aggregateFeedback = [];
             for (const evaluator of wrappedEvaluators) {
@@ -768,6 +787,7 @@ async function _evaluate(target, fields) {
         numRepetitions: fields.numRepetitions ?? 1,
         evaluatorKeys: _collectEvaluatorKeys(standardFields.evaluators),
         includeAttachments: standardFields.includeAttachments,
+        disableEvaluatorTracing: standardFields.disableEvaluatorTracing,
     }).start();
     const targetConcurrency = standardFields.targetConcurrency ?? standardFields.maxConcurrency ?? 0;
     const evaluationConcurrency = standardFields.evaluationConcurrency ?? standardFields.maxConcurrency ?? 0;
@@ -979,7 +999,25 @@ function _resolveData(data, options) {
     }
     return data;
 }
-async function wrapSummaryEvaluators(evaluators, optionsArray) {
+/**
+ * Strip evaluator-run links from an evaluator response.
+ *
+ * Used when evaluator tracing is disabled: no evaluator run is created, so a
+ * `sourceRunId` on the feedback would point at a run that does not exist.
+ */
+function _withoutSourceRunIds(response) {
+    if ("results" in response) {
+        return {
+            ...response,
+            results: response.results.map((result) => ({
+                ...result,
+                sourceRunId: undefined,
+            })),
+        };
+    }
+    return { ...response, sourceRunId: undefined };
+}
+async function wrapSummaryEvaluators(evaluators, optionsArray, tracingEnabled) {
     async function _wrap(evaluator) {
         const evalName = evaluator.name || "BatchEvaluator";
         const wrapperInner = (runs, examples) => {
@@ -999,7 +1037,11 @@ async function wrapSummaryEvaluators(evaluators, optionsArray) {
                 }
                 // Otherwise use the traditional (runs, examples) signature
                 return Promise.resolve(evaluator(runs, examples));
-            }, { ...optionsArray, name: evalName });
+            }, {
+                ...optionsArray,
+                name: evalName,
+                ...(tracingEnabled === undefined ? {} : { tracingEnabled }),
+            });
             return Promise.resolve(wrapperSuperInner(`Runs[] (Length=${runs.length})`, `Examples[] (Length=${examples.length})`));
         };
         return wrapperInner;

package/dist/index.cjs

@@ -35,6 +35,6 @@ Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, g
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_js_1.RateLimitError; } });
 Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_js_1.InternalServerError; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.10.4";
+exports.__version__ = "0.10.5";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 exports.LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.j
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
-export declare const __version__ = "0.10.4";
+export declare const __version__ = "0.10.5";
 export declare const LS_MESSAGE_VIEW_EXCLUDE: "ls_message_view_exclude";

package/dist/index.js

@@ -7,6 +7,6 @@ export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
 // Update using pnpm bump-version
-export const __version__ = "0.10.4";
+export const __version__ = "0.10.5";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 export const LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

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.