langsmith 0.8.7 → 0.8.9

package/dist/sandbox/ws_execute.d.ts

@@ -5,6 +5,14 @@
  * Install with: npm install ws
  */
 import type { WsMessage, WsRunOptions } from "./types.js";
+export declare const WS_OPEN_TIMEOUT: number | undefined;
+export declare const WS_CONNECT_BUDGET: number | undefined;
+/** Instant after which connect attempts must stop, if bounded. */
+export declare function connectDeadline(): number | undefined;
+/** Seconds left in the connect budget, or undefined when unbounded. */
+export declare function remainingBudget(deadline: number | undefined): number | undefined;
+/** Per-attempt open timeout, clamped so it cannot outlive `deadline`. */
+export declare function openTimeoutFor(deadline: number | undefined): number | undefined;
 type WsWebSocket = any;
 /** Whether the optional `ws` package could be loaded (resolved once). */
 export declare function isWsAvailable(): Promise<boolean>;
@@ -62,8 +70,10 @@ export declare function runWsStream(dataplaneUrl: string, apiKey: string | undef
  * Reconnect to an existing command over WebSocket.
  *
  * Returns a tuple of [async_message_iterator, control], same as runWsStream.
- * The iterator yields stdout, stderr, exit, and error messages.
- * No 'started' message is sent on reconnection.
+ * The iterator yields the server's 'started' acknowledgement, then stdout,
+ * stderr, exit, and error messages. That acknowledgement is the only evidence a
+ * reattachment landed for a command producing no output, so it is forwarded
+ * rather than dropped.
  */
 export declare function reconnectWsStream(dataplaneUrl: string, apiKey: string | undefined, commandId: string, options?: {
     stdoutOffset?: number;

package/dist/sandbox/ws_execute.js

@@ -4,7 +4,47 @@
  * Uses the `ws` npm package (optional peer dependency).
  * Install with: npm install ws
  */
-import { LangSmithCommandTimeoutError, LangSmithSandboxConnectionError, LangSmithSandboxOperationError, LangSmithSandboxServerReloadError, } from "./errors.js";
+import { LangSmithCommandTimeoutError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxOperationError, LangSmithSandboxServerReloadError, } from "./errors.js";
+import { getLangSmithEnvironmentVariable } from "../utils/env.js";
+/** Read a WebSocket timeout override, in seconds. `<= 0` disables it. */
+function envTimeout(name, defaultSeconds) {
+    const raw = getLangSmithEnvironmentVariable(name);
+    if (raw === undefined || raw.trim() === "")
+        return defaultSeconds;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        console.warn(`Ignoring invalid LANGSMITH_${name}=${raw}, using ${defaultSeconds}`);
+        return defaultSeconds;
+    }
+    return value > 0 ? value : undefined;
+}
+// A slow cold start is recovered by the retry loop in run(), not by waiting here.
+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);
+function nowSeconds() {
+    return performance.now() / 1000;
+}
+/** Instant after which connect attempts must stop, if bounded. */
+export function connectDeadline() {
+    return WS_CONNECT_BUDGET === undefined
+        ? undefined
+        : nowSeconds() + WS_CONNECT_BUDGET;
+}
+/** Seconds left in the connect budget, or undefined when unbounded. */
+export function remainingBudget(deadline) {
+    return deadline === undefined ? undefined : deadline - nowSeconds();
+}
+/** Per-attempt open timeout, clamped so it cannot outlive `deadline`. */
+export function openTimeoutFor(deadline) {
+    if (deadline === undefined)
+        return WS_OPEN_TIMEOUT;
+    const remaining = Math.max(deadline - nowSeconds(), 0);
+    return WS_OPEN_TIMEOUT === undefined
+        ? remaining
+        : Math.min(WS_OPEN_TIMEOUT, remaining);
+}
 // Load the optional 'ws' package once, at module load, instead of importing on
 // every call. Resolves to the WebSocket constructor, or null if 'ws' isn't
 // installed. run() reads isWsAvailable() to choose WS vs the HTTP fallback.
@@ -130,18 +170,42 @@ 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.
  */
-async function connectWs(url, headers) {
+async function connectWs(url, headers, openTimeout = WS_OPEN_TIMEOUT) {
     const { WebSocket: WS } = await ensureWs();
     return new Promise((resolve, reject) => {
-        const ws = new WS(url, { headers });
+        const ws = new WS(url, {
+            headers,
+            handshakeTimeout: openTimeout === undefined ? undefined : openTimeout * 1000,
+        });
+        let settled = false;
         ws.on("open", () => {
-            ws.removeAllListeners("error");
+            if (settled)
+                return;
+            settled = true;
             resolve(ws);
         });
+        // Attaching this suppresses ws's own "error" for a non-101 response, so the
+        // rejected upgrade cannot be misreported as a retryable socket failure. ws
+        // leaves cleanup to the handler once a listener is present.
+        ws.on("unexpected-response", (req, res) => {
+            res.resume?.();
+            req.destroy?.();
+            if (settled)
+                return;
+            settled = true;
+            reject(new LangSmithSandboxConnectionError(`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.
         ws.on("error", (err) => {
-            ws.removeAllListeners("open");
-            reject(new LangSmithSandboxConnectionError(`Failed to connect to sandbox WebSocket: ${err.message}`));
+            if (settled)
+                return;
+            settled = true;
+            reject(new LangSmithSandboxConnectTimeoutError(`Failed to connect to sandbox WebSocket: ${err.message}`));
         });
     });
 }
@@ -239,14 +303,14 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
     async function* stream() {
         let ws;
         try {
-            ws = await connectWs(wsUrl, headers);
+            ws = await connectWs(wsUrl, headers, openTimeout);
             control._bind(ws);
             // Send execute request
             const payload = {
@@ -305,8 +369,10 @@ export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
  * Reconnect to an existing command over WebSocket.
  *
  * Returns a tuple of [async_message_iterator, control], same as runWsStream.
- * The iterator yields stdout, stderr, exit, and error messages.
- * No 'started' message is sent on reconnection.
+ * The iterator yields the server's 'started' acknowledgement, then stdout,
+ * stderr, exit, and error messages. That acknowledgement is the only evidence a
+ * reattachment landed for a command producing no output, so it is forwarded
+ * rather than dropped.
  */
 export async function reconnectWsStream(dataplaneUrl, apiKey, commandId, options = {}) {
     const { stdoutOffset = 0, stderrOffset = 0, headers: extraHeaders } = options;
@@ -328,7 +394,9 @@ export async function reconnectWsStream(dataplaneUrl, apiKey, commandId, options
             // Read messages until exit or error
             for await (const msg of readWsMessages(ws)) {
                 const msgType = msg.type;
-                if (msgType === "stdout" || msgType === "stderr") {
+                if (msgType === "started" ||
+                    msgType === "stdout" ||
+                    msgType === "stderr") {
                     yield msg;
                 }
                 else if (msgType === "exit") {

package/dist/utils/v2_migration.cjs

@@ -1,7 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBackend = void 0;
+exports.getQueryBackend = getQueryBackend;
 exports.v2RunToRun = v2RunToRun;
 exports.loadTracesV2 = loadTracesV2;
+exports.QueryBackend = {
+    CLICKHOUSE_ONLY: "clickhouse_only",
+    SMITHDB_ONLY: "smithdb_only",
+    DUAL: "dual",
+};
+/** Which backend(s) `/info`'s `instance_flags` indicate for run/trace queries. */
+function getQueryBackend(instanceFlags) {
+    const flags = instanceFlags ?? {};
+    const chEnabled = Boolean(flags.ch_query_enabled ?? true);
+    const sdbEnabled = Boolean(flags.sdb_query_enabled ?? false);
+    if (!chEnabled && sdbEnabled)
+        return exports.QueryBackend.SMITHDB_ONLY;
+    if (chEnabled && sdbEnabled)
+        return exports.QueryBackend.DUAL;
+    return exports.QueryBackend.CLICKHOUSE_ONLY;
+}
 // Omitting selects from `/v2/runs/query` returns only the run ID.
 const V2_RUN_SELECTS = [
     "ID",

package/dist/utils/v2_migration.d.ts

@@ -1,6 +1,14 @@
 import type { Run as V2Run } from "../_openapi_client/resources/runs/runs.js";
 import type { Client } from "../client.js";
 import type { Run, TracerSession } from "../schemas.js";
+export declare const QueryBackend: {
+    readonly CLICKHOUSE_ONLY: "clickhouse_only";
+    readonly SMITHDB_ONLY: "smithdb_only";
+    readonly DUAL: "dual";
+};
+export type QueryBackend = (typeof QueryBackend)[keyof typeof QueryBackend];
+/** Which backend(s) `/info`'s `instance_flags` indicate for run/trace queries. */
+export declare function getQueryBackend(instanceFlags?: Record<string, unknown> | null): QueryBackend;
 export declare function v2RunToRun(run: V2Run): Run;
 export declare function loadTracesV2(client: Client, project: TracerSession, options: {
     isRoot?: boolean;

package/dist/utils/v2_migration.js

@@ -1,3 +1,19 @@
+export const QueryBackend = {
+    CLICKHOUSE_ONLY: "clickhouse_only",
+    SMITHDB_ONLY: "smithdb_only",
+    DUAL: "dual",
+};
+/** Which backend(s) `/info`'s `instance_flags` indicate for run/trace queries. */
+export function getQueryBackend(instanceFlags) {
+    const flags = instanceFlags ?? {};
+    const chEnabled = Boolean(flags.ch_query_enabled ?? true);
+    const sdbEnabled = Boolean(flags.sdb_query_enabled ?? false);
+    if (!chEnabled && sdbEnabled)
+        return QueryBackend.SMITHDB_ONLY;
+    if (chEnabled && sdbEnabled)
+        return QueryBackend.DUAL;
+    return QueryBackend.CLICKHOUSE_ONLY;
+}
 // Omitting selects from `/v2/runs/query` returns only the run ID.
 const V2_RUN_SELECTS = [
     "ID",

package/dist/utils/warn.cjs

@@ -1,10 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetWarnedMessages = _resetWarnedMessages;
 exports.warnOnce = warnOnce;
 const warnedMessages = {};
-function warnOnce(message) {
-    if (!warnedMessages[message]) {
-        console.warn(message);
-        warnedMessages[message] = true;
+/**
+ * Clear the warn-once record so a later call warns again.
+ *
+ * Test-only. `warnedMessages` is module-global and never otherwise reset, so
+ * without this a test asserting "warning X was (not) emitted" depends on whether
+ * an earlier test in the same file already consumed X.
+ *
+ * @internal
+ */
+function _resetWarnedMessages() {
+    for (const key of Object.keys(warnedMessages)) {
+        delete warnedMessages[key];
+    }
+}
+function warnOnce(message, options) {
+    const key = options?.code ?? message;
+    if (!warnedMessages[key]) {
+        warnedMessages[key] = true;
+        if (options?.type &&
+            typeof process !== "undefined" &&
+            typeof process.emitWarning === "function") {
+            process.emitWarning(message, { type: options.type, code: options.code });
+        }
+        else if (options?.type && options?.code) {
+            console.warn(`${options.type} [${options.code}]: ${message}`);
+        }
+        else {
+            console.warn(message);
+        }
     }
 }

package/dist/utils/warn.d.ts

@@ -1 +1,4 @@
-export declare function warnOnce(message: string): void;
+export declare function warnOnce(message: string, options?: {
+    type?: string;
+    code?: string;
+}): void;

package/dist/utils/warn.js

@@ -1,7 +1,32 @@
 const warnedMessages = {};
-export function warnOnce(message) {
-    if (!warnedMessages[message]) {
-        console.warn(message);
-        warnedMessages[message] = true;
+/**
+ * Clear the warn-once record so a later call warns again.
+ *
+ * Test-only. `warnedMessages` is module-global and never otherwise reset, so
+ * without this a test asserting "warning X was (not) emitted" depends on whether
+ * an earlier test in the same file already consumed X.
+ *
+ * @internal
+ */
+export function _resetWarnedMessages() {
+    for (const key of Object.keys(warnedMessages)) {
+        delete warnedMessages[key];
+    }
+}
+export function warnOnce(message, options) {
+    const key = options?.code ?? message;
+    if (!warnedMessages[key]) {
+        warnedMessages[key] = true;
+        if (options?.type &&
+            typeof process !== "undefined" &&
+            typeof process.emitWarning === "function") {
+            process.emitWarning(message, { type: options.type, code: options.code });
+        }
+        else if (options?.type && options?.code) {
+            console.warn(`${options.type} [${options.code}]: ${message}`);
+        }
+        else {
+            console.warn(message);
+        }
     }
 }

package/package.json

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

package/dist/utils/constants.cjs

@@ -1,4 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports._MIN_BACKEND_VERSION = void 0;
-exports._MIN_BACKEND_VERSION = "0.16.14rc1";

package/dist/utils/constants.d.ts

@@ -1 +0,0 @@
-export declare const _MIN_BACKEND_VERSION = "0.16.14rc1";

package/dist/utils/constants.js

@@ -1 +0,0 @@
-export const _MIN_BACKEND_VERSION = "0.16.14rc1";