langsmith 0.10.4 → 0.10.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/client.cjs +10 -0
  2. package/dist/client.d.ts +1 -0
  3. package/dist/client.js +10 -0
  4. package/dist/evaluation/_runner.cjs +47 -5
  5. package/dist/evaluation/_runner.d.ts +12 -0
  6. package/dist/evaluation/_runner.js +47 -5
  7. package/dist/index.cjs +1 -1
  8. package/dist/index.d.ts +1 -1
  9. package/dist/index.js +1 -1
  10. package/dist/sandbox/access_delegation.cjs +24 -0
  11. package/dist/sandbox/access_delegation.d.ts +15 -0
  12. package/dist/sandbox/access_delegation.js +21 -0
  13. package/dist/sandbox/client.cjs +70 -5
  14. package/dist/sandbox/client.d.ts +18 -0
  15. package/dist/sandbox/client.js +70 -5
  16. package/dist/sandbox/command_handle.cjs +34 -0
  17. package/dist/sandbox/command_handle.d.ts +10 -0
  18. package/dist/sandbox/command_handle.js +34 -0
  19. package/dist/sandbox/helpers.cjs +129 -0
  20. package/dist/sandbox/helpers.d.ts +29 -0
  21. package/dist/sandbox/helpers.js +123 -0
  22. package/dist/sandbox/index.cjs +7 -1
  23. package/dist/sandbox/index.d.ts +5 -1
  24. package/dist/sandbox/index.js +2 -0
  25. package/dist/sandbox/mounts.cjs +21 -3
  26. package/dist/sandbox/mounts.d.ts +7 -1
  27. package/dist/sandbox/mounts.js +21 -3
  28. package/dist/sandbox/proxy_config.cjs +41 -10
  29. package/dist/sandbox/proxy_config.d.ts +33 -6
  30. package/dist/sandbox/proxy_config.js +40 -10
  31. package/dist/sandbox/sandbox.cjs +160 -4
  32. package/dist/sandbox/sandbox.d.ts +71 -1
  33. package/dist/sandbox/sandbox.js +161 -5
  34. package/dist/sandbox/service_url.cjs +125 -0
  35. package/dist/sandbox/service_url.d.ts +50 -0
  36. package/dist/sandbox/service_url.js +120 -0
  37. package/dist/sandbox/types.d.ts +251 -8
  38. package/dist/sandbox/ws_execute.cjs +31 -1
  39. package/dist/sandbox/ws_execute.d.ts +9 -0
  40. package/dist/sandbox/ws_execute.js +31 -1
  41. package/dist/utils/error.cjs +17 -22
  42. package/dist/utils/error.js +17 -22
  43. package/package.json +1 -1
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Sandbox class for interacting with a specific sandbox instance.
3
3
  */
4
- import type { CaptureSnapshotOptions, DownloadURL, ExecutionResult, GenerateDownloadURLOptions, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
4
+ import type { AccessDelegation } from "./access_delegation.js";
5
+ import type { CaptureSnapshotOptions, DownloadURL, ExecutionResult, FileChunk, FileStat, GenerateDownloadURLOptions, GlobOptions, GlobResult, GrepOptions, GrepResult, ReadRangeOptions, RunConfig, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
5
6
  import { CommandHandle } from "./command_handle.js";
6
7
  /**
7
8
  * Represents an active sandbox for running commands and file operations.
@@ -62,6 +63,16 @@ export declare class Sandbox {
62
63
  readonly mem_bytes?: number;
63
64
  /** Root filesystem capacity in bytes. */
64
65
  readonly fs_capacity_bytes?: number;
66
+ /**
67
+ * User, working directory and environment this sandbox's commands run
68
+ * with. Absent on sandboxes created before the server recorded it.
69
+ */
70
+ readonly run_config?: RunConfig;
71
+ /**
72
+ * LangSmith access granted to code inside the sandbox, or undefined when it
73
+ * has none.
74
+ */
75
+ readonly access_delegation?: AccessDelegation;
65
76
  private _client;
66
77
  /**
67
78
  * Return the dataplane URL.
@@ -126,6 +137,8 @@ export declare class Sandbox {
126
137
  reconnect(commandId: string, options?: {
127
138
  stdoutOffset?: number;
128
139
  stderrOffset?: number;
140
+ stdinClosed?: boolean;
141
+ pty?: boolean;
129
142
  }): Promise<CommandHandle>;
130
143
  /**
131
144
  * Write content to a file in the sandbox.
@@ -155,6 +168,63 @@ export declare class Sandbox {
155
168
  * ```
156
169
  */
157
170
  read(path: string, timeout?: number): Promise<Uint8Array>;
171
+ /**
172
+ * Report a file's size and validators without transferring it.
173
+ *
174
+ * @param path - File path to stat.
175
+ * @param timeout - Request timeout in seconds.
176
+ * @returns The size and the `ETag` to pass to {@link readRange}.
177
+ */
178
+ stat(path: string, timeout?: number): Promise<FileStat>;
179
+ /**
180
+ * Read part of a file, for chunked reads and resumed downloads.
181
+ *
182
+ * @param path - File path to read.
183
+ * @param options - The byte range, plus optional `ifRange`/`ifNoneMatch`
184
+ * validators. A 200 answer to a ranged request means the file changed and
185
+ * the server sent it whole -- restart rather than append.
186
+ * @returns The bytes and where they sit in the file.
187
+ *
188
+ * @example
189
+ * ```typescript
190
+ * const head = await sandbox.readRange("/big.bin", { start: 0, end: 1023 });
191
+ * const next = await sandbox.readRange("/big.bin", {
192
+ * start: head.end ?? 1024,
193
+ * ifRange: head.etag,
194
+ * });
195
+ * ```
196
+ */
197
+ readRange(path: string, options: ReadRangeOptions): Promise<FileChunk>;
198
+ /**
199
+ * Find files and directories matching a pattern.
200
+ *
201
+ * @param pattern - Match against each entry's path relative to `path`.
202
+ * Supports `**` for any number of segments plus `*`, `?` and `[...]`
203
+ * within one segment.
204
+ * @param path - Absolute path of the directory to search under.
205
+ * @param options - Result cap and request options.
206
+ * @returns The matches; check `truncated` before treating them as complete.
207
+ */
208
+ glob(pattern: string, path: string, options?: GlobOptions): Promise<GlobResult>;
209
+ /**
210
+ * List a directory's immediate entries, without recursing.
211
+ *
212
+ * A convenience over {@link glob} with the pattern `*`.
213
+ *
214
+ * @param path - Absolute path of the directory to list.
215
+ * @param options - Result cap and request options.
216
+ * @returns The directory's files and subdirectories.
217
+ */
218
+ ls(path: string, options?: GlobOptions): Promise<GlobResult>;
219
+ /**
220
+ * Search file contents for a literal string.
221
+ *
222
+ * @param pattern - Literal text to search for. Not a regular expression.
223
+ * @param path - Absolute path of the directory to search under.
224
+ * @param options - Optional `glob` file filter, result cap, request options.
225
+ * @returns The matching lines; check `truncated` for completeness.
226
+ */
227
+ grep(pattern: string, path: string, options?: GrepOptions): Promise<GrepResult>;
158
228
  /**
159
229
  * Create a link that downloads one file from this sandbox.
160
230
  *
@@ -3,7 +3,7 @@
3
3
  */
4
4
  import { uuid7 } from "../uuid.js";
5
5
  import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxRetryableConnectionError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
6
- import { handleSandboxHttpError } from "./helpers.js";
6
+ import { assertRunConfigNotCombined, buildRangeHeader, fileChunkFromResponse, fileStatFromResponse, handleFileHttpError, handleSandboxHttpError, resolveCloseInput, } from "./helpers.js";
7
7
  import { CommandHandle } from "./command_handle.js";
8
8
  import { connectDeadline, isWsAvailable, openTimeoutFor, reconnectWsStream, remainingBudget, runWsStream, } from "./ws_execute.js";
9
9
  /**
@@ -137,6 +137,26 @@ export class Sandbox {
137
137
  writable: true,
138
138
  value: void 0
139
139
  });
140
+ /**
141
+ * User, working directory and environment this sandbox's commands run
142
+ * with. Absent on sandboxes created before the server recorded it.
143
+ */
144
+ Object.defineProperty(this, "run_config", {
145
+ enumerable: true,
146
+ configurable: true,
147
+ writable: true,
148
+ value: void 0
149
+ });
150
+ /**
151
+ * LangSmith access granted to code inside the sandbox, or undefined when it
152
+ * has none.
153
+ */
154
+ Object.defineProperty(this, "access_delegation", {
155
+ enumerable: true,
156
+ configurable: true,
157
+ writable: true,
158
+ value: void 0
159
+ });
140
160
  Object.defineProperty(this, "_client", {
141
161
  enumerable: true,
142
162
  configurable: true,
@@ -157,6 +177,8 @@ export class Sandbox {
157
177
  this.vCpus = data.vcpus;
158
178
  this.mem_bytes = data.mem_bytes;
159
179
  this.fs_capacity_bytes = data.fs_capacity_bytes;
180
+ this.run_config = data.run_config;
181
+ this.access_delegation = data.access_delegation;
160
182
  this._client = client;
161
183
  }
162
184
  /**
@@ -177,8 +199,10 @@ export class Sandbox {
177
199
  return this.dataplane_url;
178
200
  }
179
201
  async run(command, options = {}) {
180
- const { wait = true, onStdout, onStderr, idleTimeout, killOnDisconnect, ttlSeconds, pty, ...restOptions } = options;
202
+ const { wait = true, onStdout, onStderr, idleTimeout, killOnDisconnect, ttlSeconds, pty, closeInput, ...restOptions } = options;
181
203
  const hasCallbacks = onStdout !== undefined || onStderr !== undefined;
204
+ assertRunConfigNotCombined(restOptions);
205
+ const closeStdin = resolveCloseInput(closeInput, pty ?? false);
182
206
  if (!wait || hasCallbacks) {
183
207
  // WebSocket required for streaming / non-blocking
184
208
  const handle = await this._runWs(command, {
@@ -187,6 +211,7 @@ export class Sandbox {
187
211
  killOnDisconnect,
188
212
  ttlSeconds,
189
213
  pty,
214
+ closeInput: closeStdin,
190
215
  onStdout,
191
216
  onStderr,
192
217
  });
@@ -205,6 +230,7 @@ export class Sandbox {
205
230
  killOnDisconnect,
206
231
  ttlSeconds,
207
232
  pty,
233
+ closeInput: closeStdin,
208
234
  });
209
235
  return await handle.result;
210
236
  }
@@ -222,7 +248,7 @@ export class Sandbox {
222
248
  * @internal
223
249
  */
224
250
  async _runWs(command, options = {}) {
225
- const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout, killOnDisconnect, ttlSeconds, pty, } = options;
251
+ const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout, killOnDisconnect, ttlSeconds, pty, runConfig, closeInput: closeStdin = false, } = options;
226
252
  const dataplaneUrl = this.requireDataplaneUrl();
227
253
  const clientHeaders = this._client.getDefaultHeaders();
228
254
  // A client-supplied command_id makes execute idempotent: the daemon does
@@ -244,6 +270,8 @@ export class Sandbox {
244
270
  killOnDisconnect,
245
271
  ttlSeconds,
246
272
  pty,
273
+ runConfig,
274
+ closeStdin,
247
275
  openTimeout: openTimeoutFor(deadline),
248
276
  ...(Object.keys(clientHeaders).length > 0
249
277
  ? { headers: clientHeaders }
@@ -252,6 +280,8 @@ export class Sandbox {
252
280
  const handle = new CommandHandle(stream, control, this, {
253
281
  onStdout,
254
282
  onStderr,
283
+ stdinClosed: closeStdin,
284
+ pty: pty ?? false,
255
285
  });
256
286
  try {
257
287
  await handle._ensureStarted();
@@ -294,7 +324,7 @@ export class Sandbox {
294
324
  * @internal
295
325
  */
296
326
  async _runHttp(command, options = {}) {
297
- const { timeout = 60, env, cwd, shell = "/bin/bash" } = options;
327
+ const { timeout = 60, env, cwd, runConfig, shell = "/bin/bash" } = options;
298
328
  const dataplaneUrl = this.requireDataplaneUrl();
299
329
  const url = `${dataplaneUrl}/execute`;
300
330
  const payload = {
@@ -305,6 +335,9 @@ export class Sandbox {
305
335
  if (env !== undefined) {
306
336
  payload.env = env;
307
337
  }
338
+ if (runConfig !== undefined) {
339
+ payload.run_config = runConfig;
340
+ }
308
341
  if (cwd !== undefined) {
309
342
  payload.cwd = cwd;
310
343
  }
@@ -336,7 +369,7 @@ export class Sandbox {
336
369
  * @returns A new CommandHandle.
337
370
  */
338
371
  async reconnect(commandId, options = {}) {
339
- const { stdoutOffset = 0, stderrOffset = 0 } = options;
372
+ const { stdoutOffset = 0, stderrOffset = 0, stdinClosed = false, pty = false, } = options;
340
373
  const dataplaneUrl = this.requireDataplaneUrl();
341
374
  const clientHeaders = this._client.getDefaultHeaders();
342
375
  const [stream, control] = await reconnectWsStream(dataplaneUrl, this._client.getApiKey(), commandId, {
@@ -350,6 +383,8 @@ export class Sandbox {
350
383
  commandId,
351
384
  stdoutOffset,
352
385
  stderrOffset,
386
+ stdinClosed,
387
+ pty,
353
388
  });
354
389
  }
355
390
  /**
@@ -410,6 +445,127 @@ export class Sandbox {
410
445
  const buffer = await response.arrayBuffer();
411
446
  return new Uint8Array(buffer);
412
447
  }
448
+ /**
449
+ * Report a file's size and validators without transferring it.
450
+ *
451
+ * @param path - File path to stat.
452
+ * @param timeout - Request timeout in seconds.
453
+ * @returns The size and the `ETag` to pass to {@link readRange}.
454
+ */
455
+ async stat(path, timeout = 60) {
456
+ const dataplaneUrl = this.requireDataplaneUrl();
457
+ const url = `${dataplaneUrl}/download?path=${encodeURIComponent(path)}`;
458
+ const response = await this._client._fetch(url, {
459
+ method: "HEAD",
460
+ signal: AbortSignal.timeout(timeout * 1000),
461
+ });
462
+ if (!response.ok) {
463
+ await handleFileHttpError(response, path, this.name);
464
+ }
465
+ return fileStatFromResponse(response);
466
+ }
467
+ /**
468
+ * Read part of a file, for chunked reads and resumed downloads.
469
+ *
470
+ * @param path - File path to read.
471
+ * @param options - The byte range, plus optional `ifRange`/`ifNoneMatch`
472
+ * validators. A 200 answer to a ranged request means the file changed and
473
+ * the server sent it whole -- restart rather than append.
474
+ * @returns The bytes and where they sit in the file.
475
+ *
476
+ * @example
477
+ * ```typescript
478
+ * const head = await sandbox.readRange("/big.bin", { start: 0, end: 1023 });
479
+ * const next = await sandbox.readRange("/big.bin", {
480
+ * start: head.end ?? 1024,
481
+ * ifRange: head.etag,
482
+ * });
483
+ * ```
484
+ */
485
+ async readRange(path, options) {
486
+ const { ifRange, ifNoneMatch, timeout = 60, headers } = options;
487
+ const dataplaneUrl = this.requireDataplaneUrl();
488
+ const url = `${dataplaneUrl}/download?path=${encodeURIComponent(path)}`;
489
+ const requestHeaders = {
490
+ ...(headers ?? {}),
491
+ Range: buildRangeHeader(options),
492
+ };
493
+ if (ifRange)
494
+ requestHeaders["If-Range"] = ifRange;
495
+ if (ifNoneMatch)
496
+ requestHeaders["If-None-Match"] = ifNoneMatch;
497
+ const response = await this._client._fetch(url, {
498
+ method: "GET",
499
+ headers: requestHeaders,
500
+ signal: AbortSignal.timeout(timeout * 1000),
501
+ });
502
+ if (!response.ok && response.status !== 304) {
503
+ await handleFileHttpError(response, path, this.name);
504
+ }
505
+ return fileChunkFromResponse(response);
506
+ }
507
+ /**
508
+ * Find files and directories matching a pattern.
509
+ *
510
+ * @param pattern - Match against each entry's path relative to `path`.
511
+ * Supports `**` for any number of segments plus `*`, `?` and `[...]`
512
+ * within one segment.
513
+ * @param path - Absolute path of the directory to search under.
514
+ * @param options - Result cap and request options.
515
+ * @returns The matches; check `truncated` before treating them as complete.
516
+ */
517
+ async glob(pattern, path, options = {}) {
518
+ const body = { pattern, path };
519
+ if (options.limit !== undefined)
520
+ body.limit = options.limit;
521
+ return (await this._fileSearch("glob", body, options));
522
+ }
523
+ /**
524
+ * List a directory's immediate entries, without recursing.
525
+ *
526
+ * A convenience over {@link glob} with the pattern `*`.
527
+ *
528
+ * @param path - Absolute path of the directory to list.
529
+ * @param options - Result cap and request options.
530
+ * @returns The directory's files and subdirectories.
531
+ */
532
+ async ls(path, options = {}) {
533
+ return this.glob("*", path, options);
534
+ }
535
+ /**
536
+ * Search file contents for a literal string.
537
+ *
538
+ * @param pattern - Literal text to search for. Not a regular expression.
539
+ * @param path - Absolute path of the directory to search under.
540
+ * @param options - Optional `glob` file filter, result cap, request options.
541
+ * @returns The matching lines; check `truncated` for completeness.
542
+ */
543
+ async grep(pattern, path, options = {}) {
544
+ const body = { pattern, path };
545
+ if (options.glob !== undefined)
546
+ body.glob = options.glob;
547
+ if (options.limit !== undefined)
548
+ body.limit = options.limit;
549
+ return (await this._fileSearch("grep", body, options));
550
+ }
551
+ /**
552
+ * POST one of the read-only filesystem search endpoints.
553
+ * @internal
554
+ */
555
+ async _fileSearch(operation, body, options) {
556
+ const { timeout = 60, headers } = options;
557
+ const dataplaneUrl = this.requireDataplaneUrl();
558
+ const response = await this._client._fetch(`${dataplaneUrl}/${operation}`, {
559
+ method: "POST",
560
+ headers: { "Content-Type": "application/json", ...(headers ?? {}) },
561
+ body: JSON.stringify(body),
562
+ signal: AbortSignal.timeout(timeout * 1000),
563
+ });
564
+ if (!response.ok) {
565
+ await handleFileHttpError(response, String(body.path), this.name);
566
+ }
567
+ return response.json();
568
+ }
413
569
  /**
414
570
  * Create a link that downloads one file from this sandbox.
415
571
  *
@@ -0,0 +1,125 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ServiceLoginUrl = exports.ServiceUrl = exports.SERVICE_TOKEN_HEADER = void 0;
4
+ /** Header the sandbox router reads the minted service token from. */
5
+ exports.SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
6
+ /** Refresh this many seconds before the token actually expires. */
7
+ const REFRESH_MARGIN_SECONDS = 60;
8
+ /**
9
+ * Service URL carrying a short-lived token, refreshed as it nears expiry.
10
+ *
11
+ * Accessors are async because a refresh is a network call.
12
+ */
13
+ class ServiceUrl {
14
+ constructor(data, refresher) {
15
+ Object.defineProperty(this, "_browserUrl", {
16
+ enumerable: true,
17
+ configurable: true,
18
+ writable: true,
19
+ value: void 0
20
+ });
21
+ Object.defineProperty(this, "_serviceUrl", {
22
+ enumerable: true,
23
+ configurable: true,
24
+ writable: true,
25
+ value: void 0
26
+ });
27
+ Object.defineProperty(this, "_token", {
28
+ enumerable: true,
29
+ configurable: true,
30
+ writable: true,
31
+ value: void 0
32
+ });
33
+ Object.defineProperty(this, "_expiresAt", {
34
+ enumerable: true,
35
+ configurable: true,
36
+ writable: true,
37
+ value: void 0
38
+ });
39
+ Object.defineProperty(this, "_refresher", {
40
+ enumerable: true,
41
+ configurable: true,
42
+ writable: true,
43
+ value: void 0
44
+ });
45
+ this._browserUrl = data.browser_url ?? "";
46
+ this._serviceUrl = data.service_url ?? "";
47
+ this._token = data.token ?? "";
48
+ this._expiresAt = data.expires_at ?? "";
49
+ this._refresher = refresher;
50
+ }
51
+ _shouldRefresh() {
52
+ if (!this._refresher || !this._expiresAt)
53
+ return false;
54
+ const expires = Date.parse(this._expiresAt);
55
+ if (Number.isNaN(expires))
56
+ return false;
57
+ return (expires - Date.now()) / 1000 <= REFRESH_MARGIN_SECONDS;
58
+ }
59
+ async _maybeRefresh() {
60
+ if (!this._refresher || !this._shouldRefresh())
61
+ return;
62
+ const fresh = await this._refresher();
63
+ this._browserUrl = fresh._browserUrl;
64
+ this._serviceUrl = fresh._serviceUrl;
65
+ this._token = fresh._token;
66
+ this._expiresAt = fresh._expiresAt;
67
+ }
68
+ /** The signed token, refreshed if near expiry. */
69
+ async token() {
70
+ await this._maybeRefresh();
71
+ return this._token;
72
+ }
73
+ /** The service base URL, refreshed if near expiry. */
74
+ async serviceUrl() {
75
+ await this._maybeRefresh();
76
+ return this._serviceUrl;
77
+ }
78
+ /** The browser URL that authenticates then redirects, refreshed if near expiry. */
79
+ async browserUrl() {
80
+ await this._maybeRefresh();
81
+ return this._browserUrl;
82
+ }
83
+ /** ISO 8601 expiry of the current token, refreshed if near expiry. */
84
+ async expiresAt() {
85
+ await this._maybeRefresh();
86
+ return this._expiresAt;
87
+ }
88
+ /** Fetch a path on the service with the token header injected. */
89
+ async fetch(path = "/", init = {}) {
90
+ const base = (await this.serviceUrl()).replace(/\/+$/, "");
91
+ const url = `${base}/${path.replace(/^\/+/, "")}`;
92
+ const headers = new Headers(init.headers);
93
+ headers.set(exports.SERVICE_TOKEN_HEADER, await this.token());
94
+ return fetch(url, { ...init, headers });
95
+ }
96
+ }
97
+ exports.ServiceUrl = ServiceUrl;
98
+ /**
99
+ * Service URL gated by LangSmith login rather than a token.
100
+ *
101
+ * The grant is durable: no token, no expiry, and only usable from a browser
102
+ * signed in to LangSmith — which is why there is no fetch helper here, a
103
+ * programmatic request cannot satisfy the login.
104
+ */
105
+ class ServiceLoginUrl {
106
+ constructor(data) {
107
+ /** The URL to open in a browser. */
108
+ Object.defineProperty(this, "url", {
109
+ enumerable: true,
110
+ configurable: true,
111
+ writable: true,
112
+ value: void 0
113
+ });
114
+ /** Who may open it: "restricted" or "workspace". */
115
+ Object.defineProperty(this, "access", {
116
+ enumerable: true,
117
+ configurable: true,
118
+ writable: true,
119
+ value: void 0
120
+ });
121
+ this.url = data.browser_url || data.service_url || "";
122
+ this.access = data.access ?? "";
123
+ }
124
+ }
125
+ exports.ServiceLoginUrl = ServiceLoginUrl;
@@ -0,0 +1,50 @@
1
+ /** How a service URL is gated. Omit for a minted token. */
2
+ export type ServiceAccess = "restricted" | "workspace";
3
+ /** Header the sandbox router reads the minted service token from. */
4
+ export declare const SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
5
+ export interface ServiceUrlData {
6
+ browser_url?: string;
7
+ service_url?: string;
8
+ token?: string;
9
+ expires_at?: string;
10
+ access?: string;
11
+ }
12
+ /**
13
+ * Service URL carrying a short-lived token, refreshed as it nears expiry.
14
+ *
15
+ * Accessors are async because a refresh is a network call.
16
+ */
17
+ export declare class ServiceUrl {
18
+ private _browserUrl;
19
+ private _serviceUrl;
20
+ private _token;
21
+ private _expiresAt;
22
+ private readonly _refresher?;
23
+ constructor(data: ServiceUrlData, refresher?: () => Promise<ServiceUrl>);
24
+ private _shouldRefresh;
25
+ private _maybeRefresh;
26
+ /** The signed token, refreshed if near expiry. */
27
+ token(): Promise<string>;
28
+ /** The service base URL, refreshed if near expiry. */
29
+ serviceUrl(): Promise<string>;
30
+ /** The browser URL that authenticates then redirects, refreshed if near expiry. */
31
+ browserUrl(): Promise<string>;
32
+ /** ISO 8601 expiry of the current token, refreshed if near expiry. */
33
+ expiresAt(): Promise<string>;
34
+ /** Fetch a path on the service with the token header injected. */
35
+ fetch(path?: string, init?: RequestInit): Promise<Response>;
36
+ }
37
+ /**
38
+ * Service URL gated by LangSmith login rather than a token.
39
+ *
40
+ * The grant is durable: no token, no expiry, and only usable from a browser
41
+ * signed in to LangSmith — which is why there is no fetch helper here, a
42
+ * programmatic request cannot satisfy the login.
43
+ */
44
+ export declare class ServiceLoginUrl {
45
+ /** The URL to open in a browser. */
46
+ readonly url: string;
47
+ /** Who may open it: "restricted" or "workspace". */
48
+ readonly access: string;
49
+ constructor(data: ServiceUrlData);
50
+ }
@@ -0,0 +1,120 @@
1
+ /** Header the sandbox router reads the minted service token from. */
2
+ export const SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
3
+ /** Refresh this many seconds before the token actually expires. */
4
+ const REFRESH_MARGIN_SECONDS = 60;
5
+ /**
6
+ * Service URL carrying a short-lived token, refreshed as it nears expiry.
7
+ *
8
+ * Accessors are async because a refresh is a network call.
9
+ */
10
+ export class ServiceUrl {
11
+ constructor(data, refresher) {
12
+ Object.defineProperty(this, "_browserUrl", {
13
+ enumerable: true,
14
+ configurable: true,
15
+ writable: true,
16
+ value: void 0
17
+ });
18
+ Object.defineProperty(this, "_serviceUrl", {
19
+ enumerable: true,
20
+ configurable: true,
21
+ writable: true,
22
+ value: void 0
23
+ });
24
+ Object.defineProperty(this, "_token", {
25
+ enumerable: true,
26
+ configurable: true,
27
+ writable: true,
28
+ value: void 0
29
+ });
30
+ Object.defineProperty(this, "_expiresAt", {
31
+ enumerable: true,
32
+ configurable: true,
33
+ writable: true,
34
+ value: void 0
35
+ });
36
+ Object.defineProperty(this, "_refresher", {
37
+ enumerable: true,
38
+ configurable: true,
39
+ writable: true,
40
+ value: void 0
41
+ });
42
+ this._browserUrl = data.browser_url ?? "";
43
+ this._serviceUrl = data.service_url ?? "";
44
+ this._token = data.token ?? "";
45
+ this._expiresAt = data.expires_at ?? "";
46
+ this._refresher = refresher;
47
+ }
48
+ _shouldRefresh() {
49
+ if (!this._refresher || !this._expiresAt)
50
+ return false;
51
+ const expires = Date.parse(this._expiresAt);
52
+ if (Number.isNaN(expires))
53
+ return false;
54
+ return (expires - Date.now()) / 1000 <= REFRESH_MARGIN_SECONDS;
55
+ }
56
+ async _maybeRefresh() {
57
+ if (!this._refresher || !this._shouldRefresh())
58
+ return;
59
+ const fresh = await this._refresher();
60
+ this._browserUrl = fresh._browserUrl;
61
+ this._serviceUrl = fresh._serviceUrl;
62
+ this._token = fresh._token;
63
+ this._expiresAt = fresh._expiresAt;
64
+ }
65
+ /** The signed token, refreshed if near expiry. */
66
+ async token() {
67
+ await this._maybeRefresh();
68
+ return this._token;
69
+ }
70
+ /** The service base URL, refreshed if near expiry. */
71
+ async serviceUrl() {
72
+ await this._maybeRefresh();
73
+ return this._serviceUrl;
74
+ }
75
+ /** The browser URL that authenticates then redirects, refreshed if near expiry. */
76
+ async browserUrl() {
77
+ await this._maybeRefresh();
78
+ return this._browserUrl;
79
+ }
80
+ /** ISO 8601 expiry of the current token, refreshed if near expiry. */
81
+ async expiresAt() {
82
+ await this._maybeRefresh();
83
+ return this._expiresAt;
84
+ }
85
+ /** Fetch a path on the service with the token header injected. */
86
+ async fetch(path = "/", init = {}) {
87
+ const base = (await this.serviceUrl()).replace(/\/+$/, "");
88
+ const url = `${base}/${path.replace(/^\/+/, "")}`;
89
+ const headers = new Headers(init.headers);
90
+ headers.set(SERVICE_TOKEN_HEADER, await this.token());
91
+ return fetch(url, { ...init, headers });
92
+ }
93
+ }
94
+ /**
95
+ * Service URL gated by LangSmith login rather than a token.
96
+ *
97
+ * The grant is durable: no token, no expiry, and only usable from a browser
98
+ * signed in to LangSmith — which is why there is no fetch helper here, a
99
+ * programmatic request cannot satisfy the login.
100
+ */
101
+ export class ServiceLoginUrl {
102
+ constructor(data) {
103
+ /** The URL to open in a browser. */
104
+ Object.defineProperty(this, "url", {
105
+ enumerable: true,
106
+ configurable: true,
107
+ writable: true,
108
+ value: void 0
109
+ });
110
+ /** Who may open it: "restricted" or "workspace". */
111
+ Object.defineProperty(this, "access", {
112
+ enumerable: true,
113
+ configurable: true,
114
+ writable: true,
115
+ value: void 0
116
+ });
117
+ this.url = data.browser_url || data.service_url || "";
118
+ this.access = data.access ?? "";
119
+ }
120
+ }