langsmith 0.8.8 → 0.8.10

package/dist/client.js

@@ -8,6 +8,7 @@ import { __version__ } from "./index.js";
 import { Langsmith as OpenAPILangsmith } from "./_openapi_client/index.js";
 import { assertUuid } from "./utils/_uuid.js";
 import { warnOnce } from "./utils/warn.js";
+import { getQueryBackend, QueryBackend } from "./utils/v2_migration.js";
 import { parseHubIdentifier } from "./utils/prompts.js";
 import { raiseForStatus, isLangSmithNotFoundError, isLangSmithConflictError, } from "./utils/error.js";
 import { promptCacheSingleton, } from "./utils/prompt_cache/index.js";
@@ -154,6 +155,72 @@ export const DEFAULT_MAX_SIZE_BYTES = 1024 * 1024 * 1024; // 1GB
 const SERVER_INFO_REQUEST_TIMEOUT_MS = 10000;
 /** Maximum number of operations to batch in a single request. */
 const DEFAULT_BATCH_SIZE_LIMIT = 100;
+/**
+ * Reject header names or values that could alter a request's framing.
+ *
+ * `Headers` does this for us, and does it the same way `fetch` will.
+ */
+function assertValidHeader(name, value) {
+    new Headers({ [name]: value });
+}
+/** Reject a malformed header up front, before it can reach a request. */
+function assertValidHeaders(headers) {
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        assertValidHeader(name, value);
+    }
+}
+/**
+ * Fold a `HeadersInit` into a plain object so it can be spread.
+ *
+ * Names are matched case-insensitively with the last value winning, keeping the
+ * first spelling seen. A plain object would instead keep both spellings, which
+ * `Headers` later joins into a `"first, second"` list rather than an override.
+ * Every name and value is validated on the way through.
+ */
+function normalizeHeaders(headers) {
+    if (!headers)
+        return {};
+    const entries = headers instanceof Headers
+        ? [...headers.entries()]
+        : Array.isArray(headers)
+            ? headers.map(([name, value]) => [name, value])
+            : Object.entries(headers);
+    const normalized = {};
+    const nameByLower = new Map();
+    for (const [name, value] of entries) {
+        assertValidHeader(name, value);
+        const lowerName = name.toLowerCase();
+        const existingName = nameByLower.get(lowerName);
+        if (existingName === undefined) {
+            nameByLower.set(lowerName, name);
+            normalized[name] = value;
+        }
+        else {
+            normalized[existingName] = value;
+        }
+    }
+    return normalized;
+}
+/**
+ * Merge the caller's two header channels, then drop the `reserved` names.
+ *
+ * `overrides` wins, matched case-insensitively so a header supplied through both
+ * channels is overridden rather than turned into a `"first, second"` list.
+ */
+function mergeCallerHeaders(base, overrides, reserved) {
+    const merged = { ...base };
+    const nameByLower = new Map(Object.keys(merged).map((name) => [name.toLowerCase(), name]));
+    for (const [name, value] of Object.entries(overrides)) {
+        const lowerName = name.toLowerCase();
+        merged[nameByLower.get(lowerName) ?? name] = value;
+    }
+    for (const name of Object.keys(merged)) {
+        if (reserved.has(name.toLowerCase())) {
+            delete merged[name];
+        }
+    }
+    return merged;
+}
 export class AutoBatchQueue {
     constructor(maxSizeBytes) {
         Object.defineProperty(this, "items", {
@@ -572,13 +639,26 @@ export class Client {
             writable: true,
             value: void 0
         });
+        /** `config.fetchOptions` without its `headers`, which are merged separately. */
         Object.defineProperty(this, "fetchOptions", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "openAPIClient", {
+        Object.defineProperty(this, "_fetchOptionsHeaders", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "_openAPIClient", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_openAPIClientSignature", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -774,7 +854,8 @@ export class Client {
             config.hideInputs ?? config.anonymizer ?? defaultConfig.hideInputs;
         this.hideOutputs =
             config.hideOutputs ?? config.anonymizer ?? defaultConfig.hideOutputs;
-        this.hideMetadata = config.hideMetadata ?? defaultConfig.hideMetadata;
+        this.hideMetadata =
+            config.hideMetadata ?? config.anonymizer ?? defaultConfig.hideMetadata;
         this.anonymizer = config.anonymizer;
         this.omitTracedRuntimeInfo = config.omitTracedRuntimeInfo ?? false;
         this.autoBatchTracing = config.autoBatchTracing ?? this.autoBatchTracing;
@@ -783,8 +864,15 @@ export class Client {
             config.blockOnRootRunFinalization ?? this.blockOnRootRunFinalization;
         this.batchSizeBytesLimit = config.batchSizeBytesLimit;
         this.batchSizeLimit = config.batchSizeLimit;
-        this.fetchOptions = config.fetchOptions || {};
-        this.openAPIClient = this._newOpenAPIClient();
+        const { headers: fetchOptionsHeaders, ...fetchOptions } = config.fetchOptions || {};
+        this.fetchOptions = fetchOptions;
+        // Kept apart from `fetchOptions` so they can be merged *under* the required
+        // headers instead of replacing the whole set at each call site.
+        this._fetchOptionsHeaders = normalizeHeaders(fetchOptionsHeaders);
+        // Validated eagerly so malformed input fails at construction, but stored
+        // as given: `get headers` hands this object back to the caller.
+        assertValidHeaders(config.headers);
+        this._customHeaders = config.headers ?? {};
         this.manualFlushMode = config.manualFlushMode ?? this.manualFlushMode;
         this._tracingMode = resolveTracingMode(config.tracingMode);
         if (this._tracingMode === "otel") {
@@ -819,8 +907,6 @@ export class Client {
             // Use the global singleton instance
             this._promptCache = promptCacheSingleton;
         }
-        // Initialize custom headers
-        this._customHeaders = config.headers ?? {};
     }
     static getDefaultClientConfig() {
         const profileConfig = loadProfileClientConfig();
@@ -892,11 +978,46 @@ export class Client {
             return this.webUrl;
         }
     }
+    /**
+     * The headers this client sets from its own config, which a caller-supplied
+     * header must not replace.
+     *
+     * Only what the client *actually* supplies: passing an explicit `Authorization`
+     * or `x-api-key` header with no configured credential is a supported way to
+     * authenticate (see `hasExplicitAuthHeader`), so those must survive.
+     */
+    get _sdkControlledHeaders() {
+        const names = new Set();
+        if (this.apiKey !== undefined) {
+            names.add("x-api-key");
+        }
+        else {
+            const profileAuthHeader = this.profileAuth?.currentAuthHeader();
+            if (profileAuthHeader) {
+                names.add(profileAuthHeader.name.toLowerCase());
+            }
+        }
+        if (this.workspaceId) {
+            names.add("x-tenant-id");
+        }
+        return names;
+    }
+    /**
+     * Headers supplied by the caller, through either `config.headers` or
+     * `config.fetchOptions.headers`, with the ones this SDK sets removed.
+     *
+     * `_customHeaders` is normalized here rather than at assignment because it is
+     * public and mutable: `get headers` hands back the caller's own object, so its
+     * contents can change (and can become malformed) at any point.
+     */
+    get _callerHeaders() {
+        return mergeCallerHeaders(normalizeHeaders(this._customHeaders), this._fetchOptionsHeaders, this._sdkControlledHeaders);
+    }
     get _mergedHeaders() {
-        // Start with custom headers so they don't override required headers
+        // Start with caller-supplied headers so they don't override required headers
         const headers = {
             "User-Agent": `langsmith-js/${__version__}`,
-            ...this._customHeaders,
+            ...this._callerHeaders,
         };
         // Required headers that should not be overridden
         if (this.apiKey !== undefined) {
@@ -913,6 +1034,35 @@ export class Client {
         }
         return headers;
     }
+    /**
+     * The auth options and caller headers to build the generated client with.
+     *
+     * The generated client applies `defaultHeaders` *after* its own auth headers,
+     * so the ones this SDK sets are already dropped from `_callerHeaders` to keep
+     * the precedence of `_mergedHeaders`, where required headers win.
+     */
+    get _openAPIAuth() {
+        const headers = { ...this._callerHeaders };
+        // A caller may authenticate by supplying `x-api-key` themselves. The
+        // generated client rejects that as a header (its `validateHeaders` requires
+        // its own `apiKey` to be set), so hand it over as the `apiKey` option and
+        // drop the header to avoid sending the same value twice.
+        const callerApiKeyName = Object.keys(headers).find((name) => name.toLowerCase() === "x-api-key");
+        let apiKey = this.apiKey;
+        if (apiKey === undefined && callerApiKeyName !== undefined) {
+            apiKey = headers[callerApiKeyName] ?? undefined;
+            delete headers[callerApiKeyName];
+        }
+        if (apiKey === undefined && this.workspaceId === undefined) {
+            // Let the wrapped `fetch` supply auth (profile auth, an explicit
+            // `Authorization` header, or none at all).
+            headers["X-API-Key"] = null;
+        }
+        return {
+            apiKey,
+            defaultHeaders: Object.keys(headers).length > 0 ? headers : undefined,
+        };
+    }
     /**
      * Get or set custom headers for the client.
      * Custom headers are merged with default headers (User-Agent, x-api-key, x-tenant-id).
@@ -922,6 +1072,7 @@ export class Client {
         return this._customHeaders;
     }
     set headers(value) {
+        assertValidHeaders(value);
         this._customHeaders = value ?? {};
     }
     _getOpenAPIBaseUrl() {
@@ -932,19 +1083,36 @@ export class Client {
         }
         return url;
     }
-    _newOpenAPIClient() {
-        const defaultHeaders = this.apiKey === undefined && this.workspaceId === undefined
-            ? { "X-API-Key": null }
-            : undefined;
-        const { method: _method, headers: _headers, body: _body, signal: _signal, ...openAPIFetchOptions } = this.fetchOptions;
+    /**
+     * The generated OpenAPI client, rebuilt whenever its auth or headers change.
+     *
+     * The generated client captures `defaultHeaders` and `apiKey` when it is
+     * built, while the handwritten paths recompute `_mergedHeaders` per request.
+     * Rebuilding on change keeps the two halves from diverging when the inputs
+     * move underneath us — a caller mutating the object returned by
+     * `get headers`, or a profile whose auth header only becomes available after
+     * its token is refreshed.
+     */
+    get openAPIClient() {
+        const auth = this._openAPIAuth;
+        const signature = JSON.stringify([auth.apiKey, auth.defaultHeaders]);
+        if (this._openAPIClient === undefined ||
+            this._openAPIClientSignature !== signature) {
+            this._openAPIClientSignature = signature;
+            this._openAPIClient = this._newOpenAPIClient(auth);
+        }
+        return this._openAPIClient;
+    }
+    _newOpenAPIClient(auth = this._openAPIAuth) {
+        const { method: _method, body: _body, signal: _signal, ...openAPIFetchOptions } = this.fetchOptions;
         return new OpenAPILangsmith({
-            apiKey: this.apiKey,
+            apiKey: auth.apiKey,
             tenantID: this.workspaceId,
             baseURL: this._getOpenAPIBaseUrl(),
             timeout: this.timeout_ms,
             fetch: this._fetch,
             fetchOptions: openAPIFetchOptions,
-            defaultHeaders,
+            defaultHeaders: auth.defaultHeaders,
         });
     }
     _getPlatformEndpointPath(path) {
@@ -1349,6 +1517,9 @@ export class Client {
         const batchSizeBytes = batch.reduce((sum, item) => sum + (item.size ?? 0), 0);
         try {
             if (this.langSmithToOTELTranslator !== undefined) {
+                for (const item of batch) {
+                    item.item = await this._maskRunMetadata(item.item);
+                }
                 this._sendBatchToOTELTranslator(batch);
             }
             else {
@@ -1429,6 +1600,25 @@ export class Client {
             this.langSmithToOTELTranslator.exportBatch(operations, otelContextMap);
         }
     }
+    async _maskRunMetadata(run) {
+        if (run.extra?.metadata == null) {
+            return run;
+        }
+        return {
+            ...run,
+            extra: {
+                ...run.extra,
+                metadata: await this.processMetadata(run.extra.metadata),
+            },
+        };
+    }
+    async _mergeRuntimeEnvAndMaskMetadata(run) {
+        const merged = mergeRuntimeEnvIntoRun(run, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo);
+        if (this.omitTracedRuntimeInfo) {
+            return merged;
+        }
+        return this._maskRunMetadata(merged);
+    }
     async processRunOperation(item) {
         clearTimeout(this.autoBatchTimeout);
         this.autoBatchTimeout = undefined;
@@ -1521,7 +1711,7 @@ export class Client {
     async _checkFeedbackSessionId() {
         const docs = "https://docs.langchain.com/langsmith/smithdb-sdk-migration#feedback-create";
         const serverInfo = await this._ensureServerInfo();
-        if (serverInfo.instance_flags?.ch_query_enabled === false) {
+        if (getQueryBackend(serverInfo.instance_flags) === QueryBackend.SMITHDB_ONLY) {
             throw new Error(`sessionId must be provided when creating feedback for a run: this ` +
                 `deployment cannot locate the run without it. See ${docs}`);
         }
@@ -1585,7 +1775,7 @@ export class Client {
             }).catch(console.error);
             return;
         }
-        const mergedRunCreateParam = mergeRuntimeEnvIntoRun(runCreate, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo);
+        const mergedRunCreateParam = await this._mergeRuntimeEnvAndMaskMetadata(runCreate);
         if (options?.apiKey !== undefined) {
             headers["x-api-key"] = options.apiKey;
         }
@@ -2046,7 +2236,22 @@ export class Client {
             return res;
         });
     }
+    /** @deprecated Use `client.runs.retrieve()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide. Will be removed after Jan 31, 2027. */
     async readRun(runId, { loadChildRuns } = { loadChildRuns: false }) {
+        warnOnce("readRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.retrieve() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_READ_RUN" });
+        return this._readRun(runId, { loadChildRuns });
+    }
+    /**
+     * Fetch a run without emitting the `readRun()` deprecation warning.
+     *
+     * Internal callers use this so that a supported method doesn't warn about a
+     * deprecated one the caller never invoked.
+     *
+     * @internal
+     */
+    async _readRun(runId, { loadChildRuns } = { loadChildRuns: false }) {
         assertUuid(runId);
         let run = _normalizeRunTimestamps(await this._get(`/runs/${runId}`));
         if (loadChildRuns) {
@@ -2054,7 +2259,11 @@ export class Client {
         }
         return run;
     }
+    /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
     async getRunUrl({ runId, run, projectOpts, }) {
+        warnOnce("getRunUrl() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.getURL() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_GET_RUN_URL" });
         if (run !== undefined) {
             let sessionId;
             if (run.session_id) {
@@ -2076,7 +2285,9 @@ export class Client {
             return `${this.getHostUrl()}/o/${tenantId}/projects/p/${sessionId}/r/${run.id}?poll=true`;
         }
         else if (runId !== undefined) {
-            const run_ = await this.readRun(runId);
+            // Via _readRun() rather than readRun() so callers don't also get a
+            // readRun deprecation warning for a method they never called.
+            const run_ = await this._readRun(runId);
             if (!run_.app_path) {
                 throw new Error(`Run ${runId} has no app_path`);
             }
@@ -2088,7 +2299,7 @@ export class Client {
         }
     }
     async _loadChildRuns(run) {
-        const childRuns = await toArray(this.listRuns({
+        const childRuns = await toArray(this._listRuns({
             isRoot: false,
             projectId: run.session_id,
             traceId: run.trace_id,
@@ -2121,6 +2332,7 @@ export class Client {
     }
     /**
      * List runs from the LangSmith server.
+     * @deprecated Use `client.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide. Will be removed after Jan 31, 2027.
      * @param projectId - The ID of the project to filter by.
      * @param projectName - The name of the project to filter by.
      * @param parentRunId - The ID of the parent run to filter by.
@@ -2202,6 +2414,20 @@ export class Client {
      * });
      */
     async *listRuns(props) {
+        warnOnce("listRuns() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_LIST_RUNS" });
+        yield* this._listRuns(props);
+    }
+    /**
+     * List runs without emitting the `listRuns()` deprecation warning.
+     *
+     * Internal callers use this so that a supported method doesn't warn about a
+     * deprecated one the caller never invoked.
+     *
+     * @internal
+     */
+    async *_listRuns(props) {
         const { projectId, projectName, parentRunId, traceId, referenceExampleId, startTime, executionOrder, isRoot, runType, error, id, query, filter, traceFilter, treeFilter, limit, select, order, } = props;
         let projectIds = [];
         if (projectId) {
@@ -2335,7 +2561,11 @@ export class Client {
             }
         }
     }
+    /** @deprecated Use `client.threads.listTraces()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide. Will be removed after Jan 31, 2027. */
     async *readThread(props) {
+        warnOnce("readThread() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.threads.listTraces() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_READ_THREAD" });
         const { threadId, projectId, projectName, isRoot = true, limit, filter: userFilter, order = "asc", } = props;
         if (!projectId && !projectName) {
             throw new Error("threadId requires projectId or projectName");
@@ -2344,7 +2574,9 @@ export class Client {
         const combinedFilter = userFilter
             ? `and(${threadFilter}, ${userFilter})`
             : threadFilter;
-        yield* this.listRuns({
+        // Via _listRuns() rather than listRuns(): readThread() already warned, and it
+        // points at threads.listTraces() rather than listRuns()'s runs.query().
+        yield* this._listRuns({
             projectId: projectId ?? undefined,
             projectName: projectName ?? undefined,
             isRoot,
@@ -2353,7 +2585,11 @@ export class Client {
             order,
         });
     }
+    /** @deprecated Use `client.threads.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide. Will be removed after Jan 31, 2027. */
     async listThreads(props) {
+        warnOnce("listThreads() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.threads.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_LIST_THREADS" });
         const { projectId, projectName, limit, offset = 0, filter, startTime, isRoot = true, } = props;
         if (!projectId && !projectName) {
             throw new Error("Either projectId or projectName must be provided");
@@ -2503,7 +2739,11 @@ export class Client {
         const result = await response.json();
         return result;
     }
+    /** @deprecated Use `client.runs.share.create()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async shareRun(runId, { shareId } = {}) {
+        warnOnce("shareRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.share.create() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_SHARE_RUN" });
         const data = {
             run_id: runId,
             share_token: shareId || uuid.v4(),
@@ -2527,7 +2767,11 @@ export class Client {
         }
         return `${this.getHostUrl()}/public/${result["share_token"]}/r`;
     }
+    /** @deprecated Use `client.runs.share.delete()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async unshareRun(runId) {
+        warnOnce("unshareRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.share.delete() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_UNSHARE_RUN" });
         assertUuid(runId);
         await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2540,7 +2784,14 @@ export class Client {
             return res;
         });
     }
+    /** @deprecated Use `client.runs.retrieve({ selects: ["SHARE_URL"] })` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async readRunSharedLink(runId) {
+        warnOnce("readRunSharedLink() is deprecated and will be removed after Jan 31, 2027. " +
+            'Use client.runs.retrieve({ selects: ["SHARE_URL"] }) instead. ' +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", {
+            type: "DeprecationWarning",
+            code: "LANGSMITH_DEPRECATED_READ_RUN_SHARED_LINK",
+        });
         assertUuid(runId);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2558,7 +2809,14 @@ export class Client {
         }
         return `${this.getHostUrl()}/public/${result["share_token"]}/r`;
     }
+    /** @deprecated Use `client.public.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async listSharedRuns(shareToken, { runIds, } = {}) {
+        warnOnce("listSharedRuns() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.public.runs.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", {
+            type: "DeprecationWarning",
+            code: "LANGSMITH_DEPRECATED_LIST_SHARED_RUNS",
+        });
         const queryParams = new URLSearchParams({
             share_token: shareToken,
         });
@@ -2706,7 +2964,7 @@ export class Client {
             _hostUrl: this.getHostUrl(),
         }));
     }
-    async createProject({ projectName, description = null, metadata = null, upsert = false, projectExtra = null, referenceDatasetId = null, numExamples = null, numRepetitions = null, evaluatorKeys = null, }) {
+    async createProject({ projectName, description = null, metadata = null, upsert = false, projectExtra = null, referenceDatasetId = null, numExamples = null, numRepetitions = null, evaluatorKeys = null, tagValueIds = null, }) {
         const upsert_ = upsert ? `?upsert=true` : "";
         const endpoint = `${this.apiUrl}/sessions${upsert_}`;
         const extra = projectExtra || {};
@@ -2730,6 +2988,9 @@ export class Client {
         if (evaluatorKeys != null && evaluatorKeys.length > 0) {
             body["evaluator_keys"] = evaluatorKeys;
         }
+        if (tagValueIds !== null) {
+            body["tag_value_ids"] = tagValueIds;
+        }
         const serializedBody = JSON.stringify(body);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(endpoint, {
@@ -2973,7 +3234,7 @@ export class Client {
         const result = await response.json();
         return result;
     }
-    async createDataset(name, { description, dataType, inputsSchema, outputsSchema, metadata, } = {}) {
+    async createDataset(name, { description, dataType, inputsSchema, outputsSchema, metadata, tagValueIds, } = {}) {
         const body = {
             name,
             description,
@@ -2988,6 +3249,9 @@ export class Client {
         if (outputsSchema) {
             body.outputs_schema_definition = outputsSchema;
         }
+        if (tagValueIds !== undefined) {
+            body.tag_value_ids = tagValueIds;
+        }
         const serializedBody = JSON.stringify(body);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/datasets`, {
@@ -4147,8 +4411,9 @@ export class Client {
      * - `RunKey[]` (preferred): each entry carries the run's full lookup key, so
      *   it can be located directly without a scan. Required for workspaces served
      *   by SmithDB; routes to `POST /runs/by-key`.
-     * - `string[]`: a plain list of run IDs. This path will be deprecated in a
-     *   future release; prefer the key form. Routes to `POST /runs`.
+     * - `string[]`: a plain list of run IDs. **Deprecated**: this path will be
+     *   removed after Jan 31, 2027; prefer the key form. Routes to `POST /runs`.
+     *   See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs.
      *
      * If every element is a string (or the list is empty) it is treated as run
      * IDs; otherwise the list is treated as `RunKey` objects.
@@ -4179,6 +4444,12 @@ export class Client {
             }));
         }
         else {
+            warnOnce("Passing run IDs as strings to addRunsToAnnotationQueue() is deprecated and will be removed after Jan 31, 2027. " +
+                "Use RunKey[] instead. " +
+                "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs for the migration guide.", {
+                type: "DeprecationWarning",
+                code: "LANGSMITH_DEPRECATED_ADD_RUNS_STRING_IDS",
+            });
             url = base;
             body = JSON.stringify(runs.map((id, i) => assertUuid(id, `runs[${i}]`).toString()));
         }

package/dist/evaluation/evaluate_comparative.cjs

@@ -24,10 +24,13 @@ async function loadTracesForExperiment(client, project, options) {
     const isRoot = options.loadNested ? undefined : true;
     const runs = (await client._supportsSDBQuery())
         ? await (0, v2_migration_js_1.loadTracesV2)(client, project, { isRoot })
-        : await client.listRuns({
-            projectId: project.id,
-            executionOrder: options.loadNested ? undefined : 1,
-        });
+        : // Via _listRuns() rather than listRuns(): evaluate() is supported, so
+            // callers have nothing to migrate; how it loads traces is an
+            // implementation detail.
+            await client._listRuns({
+                projectId: project.id,
+                executionOrder: options.loadNested ? undefined : 1,
+            });
     const treeMap = {};
     const runIdMap = {};
     const results = [];

package/dist/evaluation/evaluate_comparative.js

@@ -17,10 +17,13 @@ export async function loadTracesForExperiment(client, project, options) {
     const isRoot = options.loadNested ? undefined : true;
     const runs = (await client._supportsSDBQuery())
         ? await loadTracesV2(client, project, { isRoot })
-        : await client.listRuns({
-            projectId: project.id,
-            executionOrder: options.loadNested ? undefined : 1,
-        });
+        : // Via _listRuns() rather than listRuns(): evaluate() is supported, so
+            // callers have nothing to migrate; how it loads traces is an
+            // implementation detail.
+            await client._listRuns({
+                projectId: project.id,
+                executionOrder: options.loadNested ? undefined : 1,
+            });
     const treeMap = {};
     const runIdMap = {};
     const results = [];

package/dist/experimental/vercel/_agent_type.cjs

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVercelLsAgentType = resolveVercelLsAgentType;
+exports.vercelLsAgentTypeMetadata = vercelLsAgentTypeMetadata;
+const run_trees_js_1 = require("../../run_trees.cjs");
+const traceable_js_1 = require("../../singletons/traceable.cjs");
+const ls_agent_type_js_1 = require("../../utils/ls_agent_type.cjs");
+// Vercel builds its traceable's `metadata` config eagerly, before traceable
+// itself runs — this resolver stamps `ls_agent_type` at that moment.
+// Traceable's own propagation would carry a parent's middleware/subagent/
+// compaction/"root" tag down on its own. This resolver is needed
+// for correct default tagging of the root `ls_agent_type` == root
+// and tagging of subagents.
+function resolveVercelLsAgentType(parentRunTree) {
+    const parent = parentRunTree ?? (0, traceable_js_1.getCurrentRunTree)(true);
+    if (!(0, run_trees_js_1.isRunTree)(parent))
+        return (0, ls_agent_type_js_1.resolveDefaultLsAgentType)(parent);
+    const parentTag = parent.extra?.metadata?.ls_agent_type;
+    if (typeof parentTag === "string" && ls_agent_type_js_1.NON_ROOT_LS_AGENT_TYPES.has(parentTag)) {
+        return parentTag;
+    }
+    if (parent.run_type === "tool")
+        return "subagent";
+    if (parentTag === "root")
+        return "root";
+    return undefined;
+}
+function vercelLsAgentTypeMetadata(parentRunTree) {
+    return (0, ls_agent_type_js_1.lsAgentTypeMetadata)(resolveVercelLsAgentType(parentRunTree));
+}

package/dist/experimental/vercel/_agent_type.d.ts

@@ -0,0 +1,5 @@
+import { LsAgentType } from "../../utils/ls_agent_type.js";
+export declare function resolveVercelLsAgentType(parentRunTree?: unknown): LsAgentType | undefined;
+export declare function vercelLsAgentTypeMetadata(parentRunTree?: unknown): {
+    ls_agent_type?: LsAgentType;
+};

package/dist/experimental/vercel/_agent_type.js

@@ -0,0 +1,26 @@
+import { isRunTree } from "../../run_trees.js";
+import { getCurrentRunTree } from "../../singletons/traceable.js";
+import { NON_ROOT_LS_AGENT_TYPES, lsAgentTypeMetadata, resolveDefaultLsAgentType, } from "../../utils/ls_agent_type.js";
+// Vercel builds its traceable's `metadata` config eagerly, before traceable
+// itself runs — this resolver stamps `ls_agent_type` at that moment.
+// Traceable's own propagation would carry a parent's middleware/subagent/
+// compaction/"root" tag down on its own. This resolver is needed
+// for correct default tagging of the root `ls_agent_type` == root
+// and tagging of subagents.
+export function resolveVercelLsAgentType(parentRunTree) {
+    const parent = parentRunTree ?? getCurrentRunTree(true);
+    if (!isRunTree(parent))
+        return resolveDefaultLsAgentType(parent);
+    const parentTag = parent.extra?.metadata?.ls_agent_type;
+    if (typeof parentTag === "string" && NON_ROOT_LS_AGENT_TYPES.has(parentTag)) {
+        return parentTag;
+    }
+    if (parent.run_type === "tool")
+        return "subagent";
+    if (parentTag === "root")
+        return "root";
+    return undefined;
+}
+export function vercelLsAgentTypeMetadata(parentRunTree) {
+    return lsAgentTypeMetadata(resolveVercelLsAgentType(parentRunTree));
+}