langsmith 0.8.11 → 0.8.12

package/dist/_openapi_client/resources/issues.d.ts

@@ -21,6 +21,12 @@ export type IssuesOffsetPaginationIssues = OffsetPaginationIssues<Issue>;
 export interface Issue {
     id?: string;
     actions?: unknown;
+    auto_resolution_evidence?: unknown;
+    /**
+     * Nil unless eligible: "auto_close" or "prompt". Evidence carries the deciding
+     * gate.
+     */
+    auto_resolution_state?: string;
     created_at?: string;
     description?: string;
     first_seen_at?: string;

package/dist/_openapi_client/resources/online-evaluators.cjs

@@ -60,8 +60,8 @@ class OnlineEvaluators extends resource_js_1.APIResource {
     /**
      * Returns per-day LLM evaluator spend for the requested 7-day period, grouped by
      * evaluator, resource, or run rule. Exactly one of group_by, evaluator_id,
-     * session_id, or dataset_id is required. resource_id, type, and feedback_key may
-     * be supplied with group_by to narrow listing aggregations.
+     * session_id, or dataset_id is required. resource_id, type, feedback_key, and
+     * tag_value_id may be supplied with group_by to narrow listing aggregations.
      */
     spend(query, options) {
         return this._client.get('/api/v1/platform/evaluators/spend', { query, ...options });

package/dist/_openapi_client/resources/online-evaluators.d.ts

@@ -34,8 +34,8 @@ export declare class OnlineEvaluators extends APIResource {
     /**
      * Returns per-day LLM evaluator spend for the requested 7-day period, grouped by
      * evaluator, resource, or run rule. Exactly one of group_by, evaluator_id,
-     * session_id, or dataset_id is required. resource_id, type, and feedback_key may
-     * be supplied with group_by to narrow listing aggregations.
+     * session_id, or dataset_id is required. resource_id, type, feedback_key, and
+     * tag_value_id may be supplied with group_by to narrow listing aggregations.
      */
     spend(query: OnlineEvaluatorSpendParams, options?: RequestOptions): APIPromise<GetOnlineEvaluatorSpendResponse>;
 }
@@ -286,6 +286,11 @@ export interface OnlineEvaluatorSpendParams {
      * Filter to a specific project (UUID). Mutually exclusive with group_by.
      */
     session_id?: string;
+    /**
+     * Filter grouped results to evaluators, projects, or datasets tagged with all
+     * supplied tag value IDs. Only valid with group_by.
+     */
+    tag_value_id?: Array<string>;
     /**
      * Filter grouped results by evaluator type: 'llm' or 'code'. Only valid with
      * group_by.

package/dist/_openapi_client/resources/online-evaluators.js

@@ -57,8 +57,8 @@ export class OnlineEvaluators extends APIResource {
     /**
      * Returns per-day LLM evaluator spend for the requested 7-day period, grouped by
      * evaluator, resource, or run rule. Exactly one of group_by, evaluator_id,
-     * session_id, or dataset_id is required. resource_id, type, and feedback_key may
-     * be supplied with group_by to narrow listing aggregations.
+     * session_id, or dataset_id is required. resource_id, type, feedback_key, and
+     * tag_value_id may be supplied with group_by to narrow listing aggregations.
      */
     spend(query, options) {
         return this._client.get('/api/v1/platform/evaluators/spend', { query, ...options });

package/dist/_openapi_client/resources/public/runs.d.ts

@@ -69,7 +69,7 @@ export interface RunQueryParams {
      */
     selects?: Array<'ID' | 'NAME' | 'RUN_TYPE' | 'STATUS' | 'START_TIME' | 'END_TIME' | 'LATENCY_SECONDS' | 'FIRST_TOKEN_TIME' | 'ERROR' | 'ERROR_PREVIEW' | 'EXTRA' | 'METADATA' | 'INPUTS_PREVIEW' | 'OUTPUTS_PREVIEW' | 'PARENT_RUN_ID' | 'PARENT_RUN_IDS' | 'PROJECT_ID' | 'TRACE_ID' | 'THREAD_ID' | 'DOTTED_ORDER' | 'IS_ROOT' | 'REFERENCE_DATASET_ID' | 'TOTAL_TOKENS' | 'PROMPT_TOKENS' | 'COMPLETION_TOKENS' | 'TOTAL_COST' | 'PROMPT_COST' | 'COMPLETION_COST' | 'PROMPT_TOKEN_DETAILS' | 'COMPLETION_TOKEN_DETAILS' | 'PROMPT_COST_DETAILS' | 'COMPLETION_COST_DETAILS' | 'PRICE_MODEL_ID' | 'TAGS' | 'THREAD_EVALUATION_TIME' | 'FEEDBACK_STATS'>;
     /**
-     * Header param: application/json
+     * Header param: application/json or text/event-stream
      */
     Accept?: string;
 }

package/dist/_openapi_client/resources/sandboxes/boxes.cjs

@@ -10,6 +10,8 @@ class Boxes extends resource_js_1.APIResource {
     /**
      * Create a new sandbox from a snapshot. Provide at most one of `snapshot_id` or
      * `snapshot_name`; if neither is provided, the server uses the default snapshot.
+     * `snapshot_name` accepts a Docker-style `name` or `name:tag` reference (a bare
+     * name resolves to `name:latest`).
      */
     create(body, options) {
         return this._client.post('/api/v2/sandboxes/boxes', { body, ...options });

package/dist/_openapi_client/resources/sandboxes/boxes.d.ts

@@ -6,6 +6,8 @@ export declare class Boxes extends APIResource {
     /**
      * Create a new sandbox from a snapshot. Provide at most one of `snapshot_id` or
      * `snapshot_name`; if neither is provided, the server uses the default snapshot.
+     * `snapshot_name` accepts a Docker-style `name` or `name:tag` reference (a bare
+     * name resolves to `name:latest`).
      */
     create(body: BoxCreateParams, options?: RequestOptions): APIPromise<SandboxesAPI.SandboxResponse>;
     /**
@@ -72,6 +74,12 @@ export interface BoxCreateParams {
     labels?: {
         [key: string]: string;
     };
+    /**
+     * Memory for the sandbox, in bytes. Memory is tied to CPU at 4 GiB per vCPU: omit
+     * it and it follows that ratio; set it and it must stay within 50% of the ratio
+     * for the requested CPU, so a 1 vCPU sandbox accepts 2-6 GiB. Setting memory
+     * without CPU derives the CPU from the same ratio. Maximum 64 GiB.
+     */
     mem_bytes?: number;
     mount_config?: BoxCreateParams.MountConfig;
     name?: string;
@@ -94,7 +102,16 @@ export interface BoxCreateParams {
      * Applies to this request only.
      */
     restore_memory?: boolean;
+    /**
+     * Snapshot is a Docker-style name or name:tag reference to boot from. A bare name
+     * resolves to name:latest.
+     */
+    snapshot?: string;
     snapshot_id?: string;
+    /**
+     * SnapshotName is a synonym for Snapshot, accepted for compatibility with clients
+     * that predate it. Set one or the other.
+     */
     snapshot_name?: string;
     tag_value_ids?: Array<string>;
     vcpus?: number;
@@ -439,6 +456,10 @@ export interface BoxUpdateParams {
     delete_after_stop_seconds?: number;
     fs_capacity_bytes?: number;
     idle_ttl_seconds?: number;
+    /**
+     * New memory for the sandbox, in bytes. The 4 GiB per vCPU ratio applies when the
+     * sandbox is created; a resize enforces only the maximum of 64 GiB.
+     */
     mem_bytes?: number;
     name?: string;
     proxy_config?: BoxUpdateParams.ProxyConfig;
@@ -596,6 +617,10 @@ export interface BoxCreateSnapshotParams {
     labels?: {
         [key: string]: string;
     };
+    /**
+     * mutable Docker-style tag; defaults to "latest"
+     */
+    tag?: string;
 }
 export interface BoxGenerateServiceURLParams {
     expires_in_seconds?: number;

package/dist/_openapi_client/resources/sandboxes/boxes.js

@@ -7,6 +7,8 @@ export class Boxes extends APIResource {
     /**
      * Create a new sandbox from a snapshot. Provide at most one of `snapshot_id` or
      * `snapshot_name`; if neither is provided, the server uses the default snapshot.
+     * `snapshot_name` accepts a Docker-style `name` or `name:tag` reference (a bare
+     * name resolves to `name:latest`).
      */
     create(body, options) {
         return this._client.post('/api/v2/sandboxes/boxes', { body, ...options });

package/dist/_openapi_client/resources/sandboxes/sandboxes.d.ts

@@ -4,7 +4,7 @@ import { BoxCreateParams, BoxCreateSnapshotParams, BoxGenerateServiceURLParams,
 import * as RegistriesAPI from './registries.js';
 import { Registries, RegistryCreateParams, RegistryListParams, RegistryListResponse, RegistryResponse, RegistryUpdateParams } from './registries.js';
 import * as SnapshotsAPI from './snapshots.js';
-import { SnapshotCreateParams, SnapshotListParams, Snapshots } from './snapshots.js';
+import { SnapshotCreateParams, SnapshotListParams, SnapshotRetrieveByNameResponse, Snapshots } from './snapshots.js';
 export declare class Sandboxes extends APIResource {
     boxes: BoxesAPI.Boxes;
     registries: RegistriesAPI.Registries;
@@ -411,11 +411,16 @@ export interface SnapshotResponse {
     source_sandbox_id?: string;
     status?: string;
     status_message?: string;
+    /**
+     * Tags currently resolving to this snapshot, under Name. A snapshot with no tags
+     * is dangling — addressable only by id.
+     */
+    tags?: Array<string>;
     updated_at?: string;
 }
 export declare namespace Sandboxes {
     export { type SandboxListResponse as SandboxListResponse, type SandboxResponse as SandboxResponse, type SandboxStatusResponse as SandboxStatusResponse, type ServiceURLResponse as ServiceURLResponse, type SnapshotListResponse as SnapshotListResponse, type SnapshotResponse as SnapshotResponse, };
     export { Boxes as Boxes, type BoxCreateParams as BoxCreateParams, type BoxUpdateParams as BoxUpdateParams, type BoxListParams as BoxListParams, type BoxCreateSnapshotParams as BoxCreateSnapshotParams, type BoxGenerateServiceURLParams as BoxGenerateServiceURLParams, };
     export { Registries as Registries, type RegistryListResponse as RegistryListResponse, type RegistryResponse as RegistryResponse, type RegistryCreateParams as RegistryCreateParams, type RegistryUpdateParams as RegistryUpdateParams, type RegistryListParams as RegistryListParams, };
-    export { Snapshots as Snapshots, type SnapshotCreateParams as SnapshotCreateParams, type SnapshotListParams as SnapshotListParams, };
+    export { Snapshots as Snapshots, type SnapshotRetrieveByNameResponse as SnapshotRetrieveByNameResponse, type SnapshotCreateParams as SnapshotCreateParams, type SnapshotListParams as SnapshotListParams, };
 }

package/dist/_openapi_client/resources/sandboxes/sandboxes.js

@@ -6,7 +6,7 @@ import { Boxes, } from './boxes.js';
 import * as RegistriesAPI from './registries.js';
 import { Registries, } from './registries.js';
 import * as SnapshotsAPI from './snapshots.js';
-import { Snapshots } from './snapshots.js';
+import { Snapshots, } from './snapshots.js';
 export class Sandboxes extends APIResource {
     constructor() {
         super(...arguments);

package/dist/_openapi_client/resources/sandboxes/snapshots.cjs

@@ -14,7 +14,9 @@ class Snapshots extends resource_js_1.APIResource {
         return this._client.post('/api/v2/sandboxes/snapshots', { body, ...options });
     }
     /**
-     * Get a sandbox snapshot by ID.
+     * Get a sandbox snapshot by ID or by a Docker-style reference. A bare name means
+     * name:latest, falling back to the newest ready untagged snapshot of that name. To
+     * list the tags under a name, use /api/v2/sandboxes/snapshots-by-name/{name}.
      */
     retrieve(snapshotID, options) {
         return this._client.get((0, path_js_1.path) `/api/v2/sandboxes/snapshots/${snapshotID}`, options);
@@ -27,7 +29,8 @@ class Snapshots extends resource_js_1.APIResource {
         return this._client.get('/api/v2/sandboxes/snapshots', { query, ...options });
     }
     /**
-     * Delete a snapshot by ID. The underlying storage is reclaimed asynchronously.
+     * Delete a snapshot by ID or by a Docker-style name[:tag] reference. The
+     * underlying storage is reclaimed asynchronously.
      */
     delete(snapshotID, options) {
         return this._client.delete((0, path_js_1.path) `/api/v2/sandboxes/snapshots/${snapshotID}`, {
@@ -35,5 +38,12 @@ class Snapshots extends resource_js_1.APIResource {
             headers: (0, headers_js_1.buildHeaders)([{ Accept: '*/*' }, options?.headers]),
         });
     }
+    /**
+     * Get a snapshot name and every tag under it, with the snapshot each tag resolves
+     * to. To fetch one snapshot, use /api/v2/sandboxes/snapshots/{snapshot_id}.
+     */
+    retrieveByName(name, options) {
+        return this._client.get((0, path_js_1.path) `/api/v2/sandboxes/snapshots-by-name/${name}`, options);
+    }
 }
 exports.Snapshots = Snapshots;

package/dist/_openapi_client/resources/sandboxes/snapshots.d.ts

@@ -8,7 +8,9 @@ export declare class Snapshots extends APIResource {
      */
     create(body: SnapshotCreateParams, options?: RequestOptions): APIPromise<SandboxesAPI.SnapshotResponse>;
     /**
-     * Get a sandbox snapshot by ID.
+     * Get a sandbox snapshot by ID or by a Docker-style reference. A bare name means
+     * name:latest, falling back to the newest ready untagged snapshot of that name. To
+     * list the tags under a name, use /api/v2/sandboxes/snapshots-by-name/{name}.
      */
     retrieve(snapshotID: string, options?: RequestOptions): APIPromise<SandboxesAPI.SnapshotResponse>;
     /**
@@ -17,9 +19,25 @@ export declare class Snapshots extends APIResource {
      */
     list(query?: SnapshotListParams | null | undefined, options?: RequestOptions): APIPromise<SandboxesAPI.SnapshotListResponse>;
     /**
-     * Delete a snapshot by ID. The underlying storage is reclaimed asynchronously.
+     * Delete a snapshot by ID or by a Docker-style name[:tag] reference. The
+     * underlying storage is reclaimed asynchronously.
      */
     delete(snapshotID: string, options?: RequestOptions): APIPromise<void>;
+    /**
+     * Get a snapshot name and every tag under it, with the snapshot each tag resolves
+     * to. To fetch one snapshot, use /api/v2/sandboxes/snapshots/{snapshot_id}.
+     */
+    retrieveByName(name: string, options?: RequestOptions): APIPromise<SnapshotRetrieveByNameResponse>;
+}
+export interface SnapshotRetrieveByNameResponse {
+    name?: string;
+    tags?: Array<SnapshotRetrieveByNameResponse.Tag>;
+}
+export declare namespace SnapshotRetrieveByNameResponse {
+    interface Tag {
+        snapshot_id?: string;
+        tag?: string;
+    }
 }
 export interface SnapshotCreateParams {
     docker_image: string;
@@ -33,6 +51,10 @@ export interface SnapshotCreateParams {
         [key: string]: string;
     };
     registry_id?: string;
+    /**
+     * mutable Docker-style tag; defaults to "latest"
+     */
+    tag?: string;
 }
 export interface SnapshotListParams {
     /**
@@ -70,5 +92,5 @@ export interface SnapshotListParams {
     status?: string;
 }
 export declare namespace Snapshots {
-    export { type SnapshotCreateParams as SnapshotCreateParams, type SnapshotListParams as SnapshotListParams };
+    export { type SnapshotRetrieveByNameResponse as SnapshotRetrieveByNameResponse, type SnapshotCreateParams as SnapshotCreateParams, type SnapshotListParams as SnapshotListParams, };
 }

package/dist/_openapi_client/resources/sandboxes/snapshots.js

@@ -11,7 +11,9 @@ export class Snapshots extends APIResource {
         return this._client.post('/api/v2/sandboxes/snapshots', { body, ...options });
     }
     /**
-     * Get a sandbox snapshot by ID.
+     * Get a sandbox snapshot by ID or by a Docker-style reference. A bare name means
+     * name:latest, falling back to the newest ready untagged snapshot of that name. To
+     * list the tags under a name, use /api/v2/sandboxes/snapshots-by-name/{name}.
      */
     retrieve(snapshotID, options) {
         return this._client.get(path `/api/v2/sandboxes/snapshots/${snapshotID}`, options);
@@ -24,7 +26,8 @@ export class Snapshots extends APIResource {
         return this._client.get('/api/v2/sandboxes/snapshots', { query, ...options });
     }
     /**
-     * Delete a snapshot by ID. The underlying storage is reclaimed asynchronously.
+     * Delete a snapshot by ID or by a Docker-style name[:tag] reference. The
+     * underlying storage is reclaimed asynchronously.
      */
     delete(snapshotID, options) {
         return this._client.delete(path `/api/v2/sandboxes/snapshots/${snapshotID}`, {
@@ -32,4 +35,11 @@ export class Snapshots extends APIResource {
             headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
         });
     }
+    /**
+     * Get a snapshot name and every tag under it, with the snapshot each tag resolves
+     * to. To fetch one snapshot, use /api/v2/sandboxes/snapshots/{snapshot_id}.
+     */
+    retrieveByName(name, options) {
+        return this._client.get(path `/api/v2/sandboxes/snapshots-by-name/${name}`, options);
+    }
 }

package/dist/_openapi_client/resources/threads.cjs

@@ -28,7 +28,7 @@ class Threads extends resource_js_1.APIResource {
     }
     /**
      * Query threads within a project (session), with cursor-based pagination. Returns
-     * threads matching the given time range and optional filter.
+     * threads matching the given time range and optional filters.
      *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *

package/dist/_openapi_client/resources/threads.d.ts

@@ -22,7 +22,7 @@ export declare class Threads extends APIResource {
     listTraces(threadID: string, query: ThreadListTracesParams, options?: RequestOptions): PagePromise<ThreadTracesItemsCursorGetPagination, ThreadTrace>;
     /**
      * Query threads within a project (session), with cursor-based pagination. Returns
-     * threads matching the given time range and optional filter.
+     * threads matching the given time range and optional filters.
      *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *
@@ -658,6 +658,31 @@ export interface ThreadQueryParams extends ItemsCursorPostPaginationParams {
      * `project_id` is the tracing project UUID.
      */
     project_id?: string;
+    /**
+     * `thread_filter` narrows results using a LangSmith filter expression evaluated
+     * against each complete thread summary. Self-hosted deployments require LangSmith
+     * v0.17 or later; unsupported deployments return 501. See
+     * https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language
+     * for syntax.
+     */
+    thread_filter?: string;
+    /**
+     * `trace_filter` narrows results to threads containing at least one trace whose
+     * root run matches this LangSmith filter expression. Trace-level aggregate fields
+     * are evaluated using the complete trace summary. Self-hosted deployments require
+     * LangSmith v0.17 or later; unsupported deployments return 501. See
+     * https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language
+     * for syntax.
+     */
+    trace_filter?: string;
+    /**
+     * `tree_filter` narrows results to threads containing at least one trace with a
+     * matching run anywhere in its run tree. Self-hosted deployments require LangSmith
+     * v0.17 or later; unsupported deployments return 501. See
+     * https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language
+     * for syntax.
+     */
+    tree_filter?: string;
 }
 export interface ThreadStatsParams {
     /**

package/dist/_openapi_client/resources/threads.js

@@ -25,7 +25,7 @@ export class Threads extends APIResource {
     }
     /**
      * Query threads within a project (session), with cursor-based pagination. Returns
-     * threads matching the given time range and optional filter.
+     * threads matching the given time range and optional filters.
      *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *

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.8.11";
+exports.__version__ = "0.8.12";
 // 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.8.11";
+export declare const __version__ = "0.8.12";
 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.8.11";
+export const __version__ = "0.8.12";
 // 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/client.cjs

@@ -403,6 +403,10 @@ class SandboxClient {
      * Callers can add specific status checks (e.g. 404) before calling this.
      * @internal
      */
+    _boxUrl(name, ...segments) {
+        const suffix = segments.length ? `/${segments.join("/")}` : "";
+        return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
+    }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
             method: "POST",
@@ -487,7 +491,7 @@ class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async getSandbox(name, options) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
@@ -527,7 +531,7 @@ class SandboxClient {
             deleteAfterStopSeconds === undefined) {
             return this.getSandbox(name);
         }
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const payload = {};
         if (newName !== undefined) {
             payload.name = newName;
@@ -564,7 +568,7 @@ class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async deleteSandbox(name) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const response = await this._fetch(url, { method: "DELETE" });
         if (!response.ok) {
             if (response.status === 404) {
@@ -584,7 +588,7 @@ class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async getSandboxStatus(name, options) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
+        const url = this._boxUrl(name, "status");
         const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
@@ -647,17 +651,61 @@ class SandboxClient {
      */
     async startSandbox(name, options = {}) {
         const { timeout = 120, signal } = options;
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/start`;
+        const url = this._boxUrl(name, "start");
         await this._postJson(url, {}, { signal });
         return this.waitForSandbox(name, { timeout, signal });
     }
+    /**
+     * Create a link that downloads one file from a sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. It is pinned to the sandbox and
+     * the exact path and cannot be repointed at another file. Fetching wakes a
+     * stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param name - Sandbox name.
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await client.generateDownloadURL("my-vm", "/tmp/report.pdf");
+     * console.log(link.download_url);
+     * ```
+     */
+    async generateDownloadURL(name, path, options = {}) {
+        const { expiresInSeconds, contentType, contentDisposition, signal } = options;
+        if (expiresInSeconds !== undefined && expiresInSeconds < 1) {
+            throw new errors_js_1.LangSmithValidationError(`expiresInSeconds must be greater than 0 (got ${expiresInSeconds}); ` +
+                `omit it for a link that never expires`);
+        }
+        const url = this._boxUrl(name, "download-url");
+        const payload = { path };
+        if (expiresInSeconds !== undefined) {
+            payload.expires_in_seconds = expiresInSeconds;
+        }
+        if (contentType !== undefined) {
+            payload.content_type = contentType;
+        }
+        if (contentDisposition !== undefined) {
+            payload.content_disposition = contentDisposition;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        return (await response.json());
+    }
     /**
      * Stop a running sandbox (preserves sandbox files for later restart).
      *
      * @param name - Sandbox name.
      */
     async stopSandbox(name) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/stop`;
+        const url = this._boxUrl(name, "stop");
         await this._postJson(url, {});
     }
     // =========================================================================
@@ -778,7 +826,7 @@ class SandboxClient {
      */
     async captureSnapshot(sandboxName, name, options = {}) {
         const { dockerImage, fsCapacityBytes, timeout = 60, signal } = options;
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(sandboxName)}/snapshot`;
+        const url = this._boxUrl(sandboxName, "snapshot");
         const payload = { name };
         if (dockerImage !== undefined) {
             payload.docker_image = dockerImage;

package/dist/sandbox/client.d.ts

@@ -2,7 +2,7 @@
  * Main SandboxClient class for interacting with the sandbox server API.
  */
 import { Registries } from "../_openapi_client/resources/sandboxes/registries.js";
-import type { CaptureSnapshotOptions, CreateDockerfileSnapshotOptions, CreateSandboxOptions, CreateSnapshotOptions, ListSnapshotsOptions, ResourceStatus, SandboxClientConfig, Snapshot, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, WaitForSnapshotOptions } from "./types.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";
 /**
  * Client for interacting with the Sandbox Server API.
@@ -64,6 +64,7 @@ export declare class SandboxClient {
      * ```
      */
     get registries(): Registries;
+    private _postJson;
     /**
      * Create a new Sandbox.
      *
@@ -181,6 +182,31 @@ export declare class SandboxClient {
      * @returns Sandbox in "ready" status.
      */
     startSandbox(name: string, options?: StartSandboxOptions): Promise<Sandbox>;
+    /**
+     * Create a link that downloads one file from a sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. It is pinned to the sandbox and
+     * the exact path and cannot be repointed at another file. Fetching wakes a
+     * stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param name - Sandbox name.
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await client.generateDownloadURL("my-vm", "/tmp/report.pdf");
+     * console.log(link.download_url);
+     * ```
+     */
+    generateDownloadURL(name: string, path: string, options?: GenerateDownloadURLOptions): Promise<DownloadURL>;
     /**
      * Stop a running sandbox (preserves sandbox files for later restart).
      *

package/dist/sandbox/client.js

@@ -400,6 +400,10 @@ export class SandboxClient {
      * Callers can add specific status checks (e.g. 404) before calling this.
      * @internal
      */
+    _boxUrl(name, ...segments) {
+        const suffix = segments.length ? `/${segments.join("/")}` : "";
+        return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
+    }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
             method: "POST",
@@ -484,7 +488,7 @@ export class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async getSandbox(name, options) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
@@ -524,7 +528,7 @@ export class SandboxClient {
             deleteAfterStopSeconds === undefined) {
             return this.getSandbox(name);
         }
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const payload = {};
         if (newName !== undefined) {
             payload.name = newName;
@@ -561,7 +565,7 @@ export class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async deleteSandbox(name) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const response = await this._fetch(url, { method: "DELETE" });
         if (!response.ok) {
             if (response.status === 404) {
@@ -581,7 +585,7 @@ export class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async getSandboxStatus(name, options) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
+        const url = this._boxUrl(name, "status");
         const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
@@ -644,17 +648,61 @@ export class SandboxClient {
      */
     async startSandbox(name, options = {}) {
         const { timeout = 120, signal } = options;
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/start`;
+        const url = this._boxUrl(name, "start");
         await this._postJson(url, {}, { signal });
         return this.waitForSandbox(name, { timeout, signal });
     }
+    /**
+     * Create a link that downloads one file from a sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. It is pinned to the sandbox and
+     * the exact path and cannot be repointed at another file. Fetching wakes a
+     * stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param name - Sandbox name.
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await client.generateDownloadURL("my-vm", "/tmp/report.pdf");
+     * console.log(link.download_url);
+     * ```
+     */
+    async generateDownloadURL(name, path, options = {}) {
+        const { expiresInSeconds, contentType, contentDisposition, signal } = options;
+        if (expiresInSeconds !== undefined && expiresInSeconds < 1) {
+            throw new LangSmithValidationError(`expiresInSeconds must be greater than 0 (got ${expiresInSeconds}); ` +
+                `omit it for a link that never expires`);
+        }
+        const url = this._boxUrl(name, "download-url");
+        const payload = { path };
+        if (expiresInSeconds !== undefined) {
+            payload.expires_in_seconds = expiresInSeconds;
+        }
+        if (contentType !== undefined) {
+            payload.content_type = contentType;
+        }
+        if (contentDisposition !== undefined) {
+            payload.content_disposition = contentDisposition;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        return (await response.json());
+    }
     /**
      * Stop a running sandbox (preserves sandbox files for later restart).
      *
      * @param name - Sandbox name.
      */
     async stopSandbox(name) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/stop`;
+        const url = this._boxUrl(name, "stop");
         await this._postJson(url, {});
     }
     // =========================================================================
@@ -775,7 +823,7 @@ export class SandboxClient {
      */
     async captureSnapshot(sandboxName, name, options = {}) {
         const { dockerImage, fsCapacityBytes, timeout = 60, signal } = options;
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(sandboxName)}/snapshot`;
+        const url = this._boxUrl(sandboxName, "snapshot");
         const payload = { name };
         if (dockerImage !== undefined) {
             payload.docker_image = dockerImage;

package/dist/sandbox/errors.cjs

@@ -7,7 +7,7 @@
  * properties for specific handling when needed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithStreamEndedBeforeStartedError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = void 0;
+exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithStreamEndedBeforeStartedError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxRetryableConnectionError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = void 0;
 /**
  * Base exception for sandbox client errors.
  */
@@ -53,6 +53,19 @@ class LangSmithSandboxConnectionError extends LangSmithSandboxError {
     }
 }
 exports.LangSmithSandboxConnectionError = LangSmithSandboxConnectionError;
+/**
+ * Raised when a transient connection failure occurs before a command starts.
+ *
+ * `run()` retries this error with the same command ID so the server can
+ * deduplicate an attempt whose outcome is unknown.
+ */
+class LangSmithSandboxRetryableConnectionError extends LangSmithSandboxConnectionError {
+    constructor(message) {
+        super(message);
+        this.name = "LangSmithSandboxRetryableConnectionError";
+    }
+}
+exports.LangSmithSandboxRetryableConnectionError = LangSmithSandboxRetryableConnectionError;
 // =============================================================================
 // Resource Errors (type-based, with resourceType property)
 // =============================================================================
@@ -375,12 +388,10 @@ exports.LangSmithStreamEndedBeforeStartedError = LangSmithStreamEndedBeforeStart
 /**
  * Thrown when the socket fails or times out before the WebSocket handshake.
  *
- * Distinct from its parent because it is safely retryable: the execute frame
- * was never sent, so re-issuing the same command_id cannot double-run a
- * command. run() retries this with backoff; a plain connection error (a
- * rejected handshake) is permanent and propagates immediately.
+ * The execute frame was never sent, so re-issuing the same command ID cannot
+ * double-run a command.
  */
-class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxRetryableConnectionError {
     constructor(message) {
         super(message);
         this.name = "LangSmithSandboxConnectTimeoutError";

package/dist/sandbox/errors.d.ts

@@ -31,6 +31,15 @@ export declare class LangSmithSandboxAuthenticationError extends LangSmithSandbo
 export declare class LangSmithSandboxConnectionError extends LangSmithSandboxError {
     constructor(message: string);
 }
+/**
+ * Raised when a transient connection failure occurs before a command starts.
+ *
+ * `run()` retries this error with the same command ID so the server can
+ * deduplicate an attempt whose outcome is unknown.
+ */
+export declare class LangSmithSandboxRetryableConnectionError extends LangSmithSandboxConnectionError {
+    constructor(message: string);
+}
 /**
  * Raised when a resource is not found.
  */
@@ -168,12 +177,10 @@ export declare class LangSmithStreamEndedBeforeStartedError extends LangSmithSan
 /**
  * Thrown when the socket fails or times out before the WebSocket handshake.
  *
- * Distinct from its parent because it is safely retryable: the execute frame
- * was never sent, so re-issuing the same command_id cannot double-run a
- * command. run() retries this with backoff; a plain connection error (a
- * rejected handshake) is permanent and propagates immediately.
+ * The execute frame was never sent, so re-issuing the same command ID cannot
+ * double-run a command.
  */
-export declare class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+export declare class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxRetryableConnectionError {
     constructor(message: string);
 }
 /**

package/dist/sandbox/errors.js

@@ -46,6 +46,18 @@ export class LangSmithSandboxConnectionError extends LangSmithSandboxError {
         this.name = "LangSmithSandboxConnectionError";
     }
 }
+/**
+ * Raised when a transient connection failure occurs before a command starts.
+ *
+ * `run()` retries this error with the same command ID so the server can
+ * deduplicate an attempt whose outcome is unknown.
+ */
+export class LangSmithSandboxRetryableConnectionError extends LangSmithSandboxConnectionError {
+    constructor(message) {
+        super(message);
+        this.name = "LangSmithSandboxRetryableConnectionError";
+    }
+}
 // =============================================================================
 // Resource Errors (type-based, with resourceType property)
 // =============================================================================
@@ -354,12 +366,10 @@ export class LangSmithStreamEndedBeforeStartedError extends LangSmithSandboxOper
 /**
  * Thrown when the socket fails or times out before the WebSocket handshake.
  *
- * Distinct from its parent because it is safely retryable: the execute frame
- * was never sent, so re-issuing the same command_id cannot double-run a
- * command. run() retries this with backoff; a plain connection error (a
- * rejected handshake) is permanent and propagates immediately.
+ * The execute frame was never sent, so re-issuing the same command ID cannot
+ * double-run a command.
  */
-export class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+export class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxRetryableConnectionError {
     constructor(message) {
         super(message);
         this.name = "LangSmithSandboxConnectTimeoutError";

package/dist/sandbox/index.cjs

@@ -29,7 +29,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = exports.s3Mount = exports.mountConfig = exports.gitMount = exports.gcsMount = exports.contextHubMount = exports.workspaceSecret = exports.proxyConfig = exports.opaqueSecret = exports.gcpAuth = exports.awsAuth = exports.CommandHandle = exports.Sandbox = exports.SandboxClient = void 0;
+exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithSandboxRetryableConnectionError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = exports.s3Mount = exports.mountConfig = exports.gitMount = exports.gcsMount = exports.contextHubMount = exports.workspaceSecret = exports.proxyConfig = exports.opaqueSecret = exports.gcpAuth = exports.awsAuth = exports.CommandHandle = exports.Sandbox = exports.SandboxClient = void 0;
 // Main classes
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_js_1.SandboxClient; } });
@@ -56,6 +56,7 @@ Object.defineProperty(exports, "LangSmithSandboxError", { enumerable: true, get:
 Object.defineProperty(exports, "LangSmithSandboxAPIError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxAPIError; } });
 Object.defineProperty(exports, "LangSmithSandboxAuthenticationError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxAuthenticationError; } });
 Object.defineProperty(exports, "LangSmithSandboxConnectionError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxConnectionError; } });
+Object.defineProperty(exports, "LangSmithSandboxRetryableConnectionError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxRetryableConnectionError; } });
 Object.defineProperty(exports, "LangSmithSandboxConnectTimeoutError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxConnectTimeoutError; } });
 Object.defineProperty(exports, "LangSmithSandboxServerReloadError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxServerReloadError; } });
 // Resource errors (type-based with resourceType attribute)

package/dist/sandbox/index.d.ts

@@ -32,5 +32,5 @@ export { Sandbox } from "./sandbox.js";
 export { CommandHandle } from "./command_handle.js";
 export { awsAuth, gcpAuth, opaqueSecret, proxyConfig, workspaceSecret, } from "./proxy_config.js";
 export { contextHubMount, gcsMount, gitMount, mountConfig, s3Mount, } from "./mounts.js";
-export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceStatus, Snapshot, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, SandboxAccessControl, SandboxAwsAuthRule, SandboxAwsMountAuthConfig, SandboxGcpAuthRule, SandboxGcpMountAuthConfig, SandboxMountAuth, SandboxMountAuthConfig, SandboxMountConfig, SandboxProxyConfig, SandboxProxyRule, SandboxProxySecret, SandboxMount, MountCacheConfig, ContextHubMountConfig, ContextHubMountSpec, GCSMountConfig, GCSMountSpec, GitMountConfig, GitMountRefSpec, GitMountSpec, S3MountConfig, S3MountSpec, CreateSnapshotOptions, CreateDockerfileSnapshotOptions, CaptureSnapshotOptions, ListSnapshotsOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, } from "./types.js";
-export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";
+export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceStatus, Snapshot, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, SandboxAccessControl, SandboxAwsAuthRule, SandboxAwsMountAuthConfig, SandboxGcpAuthRule, SandboxGcpMountAuthConfig, SandboxMountAuth, SandboxMountAuthConfig, SandboxMountConfig, SandboxProxyConfig, SandboxProxyRule, SandboxProxySecret, SandboxMount, MountCacheConfig, ContextHubMountConfig, ContextHubMountSpec, GCSMountConfig, GCSMountSpec, GitMountConfig, GitMountRefSpec, GitMountSpec, S3MountConfig, S3MountSpec, CreateSnapshotOptions, CreateDockerfileSnapshotOptions, CaptureSnapshotOptions, DownloadContentDisposition, DownloadURL, GenerateDownloadURLOptions, ListSnapshotsOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, } from "./types.js";
+export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxRetryableConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/sandbox/index.js

@@ -36,7 +36,7 @@ export { contextHubMount, gcsMount, gitMount, mountConfig, s3Mount, } from "./mo
 // Errors
 export { 
 // Base and connection errors
-LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, 
+LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxRetryableConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, 
 // Resource errors (type-based with resourceType attribute)
 LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, 
 // Validation and quota errors

package/dist/sandbox/sandbox.cjs

@@ -264,7 +264,7 @@ class Sandbox {
                 // Idempotent re-issue (same command_id): neither an early close nor a
                 // failed connect can have started a second command.
                 if (!(e instanceof errors_js_1.LangSmithStreamEndedBeforeStartedError) &&
-                    !(e instanceof errors_js_1.LangSmithSandboxConnectTimeoutError)) {
+                    !(e instanceof errors_js_1.LangSmithSandboxRetryableConnectionError)) {
                     throw e;
                 }
                 attempt++;
@@ -410,6 +410,32 @@ class Sandbox {
         const buffer = await response.arrayBuffer();
         return new Uint8Array(buffer);
     }
+    /**
+     * Create a link that downloads one file from this sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. Fetching wakes a stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await sandbox.generateDownloadURL("/tmp/report.pdf", {
+     *   expiresInSeconds: 3600,
+     * });
+     * console.log(link.download_url);
+     * ```
+     */
+    async generateDownloadURL(path, options = {}) {
+        return this._client.generateDownloadURL(this.name, path, options);
+    }
     /**
      * Delete this sandbox.
      *

package/dist/sandbox/sandbox.d.ts

@@ -1,7 +1,7 @@
 /**
  * Sandbox class for interacting with a specific sandbox instance.
  */
-import type { CaptureSnapshotOptions, ExecutionResult, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
+import type { CaptureSnapshotOptions, DownloadURL, ExecutionResult, GenerateDownloadURLOptions, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
 import { CommandHandle } from "./command_handle.js";
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -155,6 +155,30 @@ export declare class Sandbox {
      * ```
      */
     read(path: string, timeout?: number): Promise<Uint8Array>;
+    /**
+     * Create a link that downloads one file from this sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. Fetching wakes a stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await sandbox.generateDownloadURL("/tmp/report.pdf", {
+     *   expiresInSeconds: 3600,
+     * });
+     * console.log(link.download_url);
+     * ```
+     */
+    generateDownloadURL(path: string, options?: GenerateDownloadURLOptions): Promise<DownloadURL>;
     /**
      * Delete this sandbox.
      *

package/dist/sandbox/sandbox.js

@@ -2,7 +2,7 @@
  * Sandbox class for interacting with a specific sandbox instance.
  */
 import { uuid7 } from "../uuid.js";
-import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxConnectTimeoutError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
+import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxRetryableConnectionError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
 import { handleSandboxHttpError } from "./helpers.js";
 import { CommandHandle } from "./command_handle.js";
 import { connectDeadline, isWsAvailable, openTimeoutFor, reconnectWsStream, remainingBudget, runWsStream, } from "./ws_execute.js";
@@ -261,7 +261,7 @@ export class Sandbox {
                 // Idempotent re-issue (same command_id): neither an early close nor a
                 // failed connect can have started a second command.
                 if (!(e instanceof LangSmithStreamEndedBeforeStartedError) &&
-                    !(e instanceof LangSmithSandboxConnectTimeoutError)) {
+                    !(e instanceof LangSmithSandboxRetryableConnectionError)) {
                     throw e;
                 }
                 attempt++;
@@ -407,6 +407,32 @@ export class Sandbox {
         const buffer = await response.arrayBuffer();
         return new Uint8Array(buffer);
     }
+    /**
+     * Create a link that downloads one file from this sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. Fetching wakes a stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await sandbox.generateDownloadURL("/tmp/report.pdf", {
+     *   expiresInSeconds: 3600,
+     * });
+     * console.log(link.download_url);
+     * ```
+     */
+    async generateDownloadURL(path, options = {}) {
+        return this._client.generateDownloadURL(this.name, path, options);
+    }
     /**
      * Delete this sandbox.
      *

package/dist/sandbox/types.d.ts

@@ -559,6 +559,41 @@ export interface CaptureSnapshotOptions {
     /** AbortSignal for cancellation. */
     signal?: AbortSignal;
 }
+/**
+ * How a download link asks the browser to handle the file.
+ */
+export type DownloadContentDisposition = "attachment" | "inline";
+/**
+ * Options for minting a sandbox file download link.
+ */
+export interface GenerateDownloadURLOptions {
+    /**
+     * Link TTL in seconds. Omit for a link that never expires.
+     */
+    expiresInSeconds?: number;
+    /** Content-Type to serve the file as. */
+    contentType?: string;
+    /** Content-Disposition to serve the file with. */
+    contentDisposition?: DownloadContentDisposition;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * A link that downloads one sandbox file with no LangSmith credential.
+ *
+ * The link is pinned to the sandbox, the file path, and the response headers,
+ * so it cannot be repointed at another file. It is pinned to the path rather
+ * than to a snapshot of the contents, so the file must not be modified while
+ * the link is in use.
+ */
+export interface DownloadURL {
+    /** The full URL to fetch. Supports GET, HEAD, and Range. */
+    download_url: string;
+    /** The signed token embedded in `download_url`. */
+    token: string;
+    /** Expiry timestamp, or null for a link that never expires. */
+    expires_at: string | null;
+}
 /**
  * Options for listing snapshots. All fields are optional and independent.
  *

package/dist/sandbox/ws_execute.cjs

@@ -35,6 +35,7 @@ exports.WS_OPEN_TIMEOUT = envTimeout("SANDBOX_WS_TIMEOUT_OPEN", 30);
 // Ceiling on the whole connect phase. Without it, retrying a blackholed
 // handshake costs MAX_AUTO_RECONNECTS + 1 full open timeouts plus backoff.
 exports.WS_CONNECT_BUDGET = envTimeout("SANDBOX_WS_TIMEOUT_CONNECT_BUDGET", 120);
+const RETRYABLE_HANDSHAKE_STATUS_CODES = new Set([500, 502, 503, 504]);
 function nowSeconds() {
     return performance.now() / 1000;
 }
@@ -184,8 +185,8 @@ function raiseForWsError(msg, commandId = "") {
  * Create a ws WebSocket connection and return a promise that resolves when open
  * or rejects on error.
  *
- * A socket-level failure rejects with the retryable connect-timeout error; a
- * non-101 response rejects with the permanent connection error.
+ * Socket-level failures and transient 5xx responses are retryable. Other
+ * non-101 responses are permanent connection errors.
  */
 async function connectWs(url, headers, openTimeout = exports.WS_OPEN_TIMEOUT) {
     const { WebSocket: WS } = await ensureWs();
@@ -210,7 +211,10 @@ async function connectWs(url, headers, openTimeout = exports.WS_OPEN_TIMEOUT) {
             if (settled)
                 return;
             settled = true;
-            reject(new errors_js_1.LangSmithSandboxConnectionError(`WebSocket upgrade to ${url} rejected by server (HTTP ${res.statusCode})`));
+            const ErrorType = RETRYABLE_HANDSHAKE_STATUS_CODES.has(res.statusCode ?? 0)
+                ? errors_js_1.LangSmithSandboxRetryableConnectionError
+                : errors_js_1.LangSmithSandboxConnectionError;
+            reject(new ErrorType(`WebSocket upgrade to ${url} rejected by server (HTTP ${res.statusCode})`));
         });
         // Stays attached after settling so a late error has a listener and cannot
         // become an unhandled 'error' event.

package/dist/sandbox/ws_execute.js

@@ -4,7 +4,7 @@
  * Uses the `ws` npm package (optional peer dependency).
  * Install with: npm install ws
  */
-import { LangSmithCommandTimeoutError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxOperationError, LangSmithSandboxServerReloadError, } from "./errors.js";
+import { LangSmithCommandTimeoutError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxOperationError, LangSmithSandboxRetryableConnectionError, LangSmithSandboxServerReloadError, } from "./errors.js";
 import { getLangSmithEnvironmentVariable } from "../utils/env.js";
 /** Read a WebSocket timeout override, in seconds. `<= 0` disables it. */
 function envTimeout(name, defaultSeconds) {
@@ -23,6 +23,7 @@ export const WS_OPEN_TIMEOUT = envTimeout("SANDBOX_WS_TIMEOUT_OPEN", 30);
 // Ceiling on the whole connect phase. Without it, retrying a blackholed
 // handshake costs MAX_AUTO_RECONNECTS + 1 full open timeouts plus backoff.
 export const WS_CONNECT_BUDGET = envTimeout("SANDBOX_WS_TIMEOUT_CONNECT_BUDGET", 120);
+const RETRYABLE_HANDSHAKE_STATUS_CODES = new Set([500, 502, 503, 504]);
 function nowSeconds() {
     return performance.now() / 1000;
 }
@@ -171,8 +172,8 @@ export function raiseForWsError(msg, commandId = "") {
  * Create a ws WebSocket connection and return a promise that resolves when open
  * or rejects on error.
  *
- * A socket-level failure rejects with the retryable connect-timeout error; a
- * non-101 response rejects with the permanent connection error.
+ * Socket-level failures and transient 5xx responses are retryable. Other
+ * non-101 responses are permanent connection errors.
  */
 async function connectWs(url, headers, openTimeout = WS_OPEN_TIMEOUT) {
     const { WebSocket: WS } = await ensureWs();
@@ -197,7 +198,10 @@ async function connectWs(url, headers, openTimeout = WS_OPEN_TIMEOUT) {
             if (settled)
                 return;
             settled = true;
-            reject(new LangSmithSandboxConnectionError(`WebSocket upgrade to ${url} rejected by server (HTTP ${res.statusCode})`));
+            const ErrorType = RETRYABLE_HANDSHAKE_STATUS_CODES.has(res.statusCode ?? 0)
+                ? LangSmithSandboxRetryableConnectionError
+                : LangSmithSandboxConnectionError;
+            reject(new ErrorType(`WebSocket upgrade to ${url} rejected by server (HTTP ${res.statusCode})`));
         });
         // Stays attached after settling so a late error has a listener and cannot
         // become an unhandled 'error' event.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "pnpm@10.33.0",
   "files": [