@lmnr-ai/client 0.8.26 → 0.8.28

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, RolloutParam, SpanType, StringUUID } from "@lmnr-ai/types";
+import { CachedSpan, Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, StringUUID } from "@lmnr-ai/types";
 
 //#region src/resources/index.d.ts
 declare class BaseResource {
@@ -257,49 +257,83 @@ declare class EvaluatorsResource extends BaseResource {
 }
 //#endregion
 //#region src/resources/rollout-sessions.d.ts
+/**
+ * Result of a debug-replay cache lookup (debug-replay v2).
+ *
+ *  - `hit`  — the server served a cached response for this input hash; replay it
+ *             and mark the span CACHED.
+ *  - `miss` — no cache entry; the caller latches process-wide live mode and runs
+ *             every subsequent call live.
+ *  - `live` — run THIS call live without latching (server COLD warmup-timeout
+ *             degrade, or any non-OK / transport error here).
+ */
+type CacheOutcome = {
+  kind: "hit";
+  cached: CachedSpan;
+} | {
+  kind: "miss";
+} | {
+  kind: "live";
+};
 declare class RolloutSessionsResource extends BaseResource {
   constructor(baseHttpUrl: string, projectApiKey: string);
   /**
-   * Connects to the SSE stream for rollout debugging sessions
-   * Returns the Response object for streaming SSE events
+   * Idempotently register (upsert) a debug session on the backend, keyed on the
+   * SDK-supplied session id. The backend stores the row so the session is
+   * visible in the UI; a null/omitted name never clobbers a name set elsewhere.
+   *
+   * Returns the backend-resolved `projectId` (derived from the API key) so the
+   * caller can build the debugger URL; null if the body can't be parsed.
    */
-  connect({
+  register({
     sessionId,
-    name,
-    params,
-    signal
+    name
   }: {
     sessionId: string;
-    params: RolloutParam[];
-    name: string;
-    signal?: AbortSignal;
-  }): Promise<Response>;
-  delete({
-    sessionId
+    name?: string;
+  }): Promise<string | null>;
+  /**
+   * Rename an existing debug session. Update-only: the backend returns 404 (and
+   * this throws) when the session id is unknown for the project, so a mistyped
+   * id surfaces as an error rather than silently creating a session. Creation
+   * stays the SDK's job via {@link register}.
+   */
+  setName({
+    sessionId,
+    name
   }: {
     sessionId: string;
+    name: string;
   }): Promise<void>;
-  setStatus({
+  /**
+   * Look up the debug-replay cache for a single LLM call (debug-replay v2).
+   *
+   * The server is keyed by `inputHash` (hex blake3 of the canonicalized,
+   * system-stripped input messages). It returns one of three outcomes:
+   *   - `{ outcome: "hit", response }` — a cached response to replay.
+   *   - `{ outcome: "miss" }`          — no entry; caller latches live mode.
+   *   - `{ outcome: "live" }`          — run this call live (COLD degrade).
+   *
+   * Error posture: a non-OK response or a transport error degrades to
+   * `{ kind: "live" }` for THIS call only — it never throws and never latches
+   * the process-wide live flag (only a real MISS does that). This keeps a flaky
+   * cache backend from turning a replay into a crash.
+   */
+  cache({
     sessionId,
-    status
+    replayTraceId,
+    cacheUntil,
+    inputHash
   }: {
     sessionId: string;
-    status: 'PENDING' | 'RUNNING' | 'FINISHED' | 'STOPPED';
-  }): Promise<void>;
-  sendSpanUpdate({
-    sessionId,
-    span
+    replayTraceId: string;
+    cacheUntil: string;
+    inputHash: string;
+  }): Promise<CacheOutcome>;
+  delete({
+    sessionId
   }: {
     sessionId: string;
-    span: {
-      name: string;
-      startTime: string;
-      spanId: string;
-      traceId: string;
-      parentSpanId: string | undefined;
-      attributes: Record<string, any>;
-      spanType: SpanType;
-    };
   }): Promise<void>;
 }
 //#endregion
@@ -371,13 +405,16 @@ declare class TracesResource extends BaseResource {
    *
    * A 404 response (the trace was not found in the project — typically because
    * it has not been flushed yet) is logged as a warning and the call returns
-   * without throwing; any other non-OK status throws.
+   * without throwing, since the 404 may be expected when pushing too soon
+   * after the trace run. Pass `failOnNotFound: true` to throw instead (e.g.
+   * CLI callers that must report the failure). Any other non-OK status throws.
    *
    * @param traceId - The trace id to push metadata to. Accepts a UUID string
    *   or a 32-char OTel hex trace id.
    * @param metadata - The metadata patch. Top-level keys are merged into the
    *   trace's existing metadata. Must be non-empty (the server rejects empty
    *   patches with 400).
+   * @param options - `failOnNotFound`: throw on 404 instead of warn-and-return.
    * @example
    * ```typescript
    * import { Laminar, observe, LaminarClient } from "@lmnr-ai/lmnr";
@@ -399,7 +436,9 @@ declare class TracesResource extends BaseResource {
    * }
    * ```
    */
-  pushMetadata(traceId: string, metadata: Record<string, unknown>): Promise<void>;
+  pushMetadata(traceId: string, metadata: Record<string, unknown>, options?: {
+    failOnNotFound?: boolean;
+  }): Promise<void>;
 }
 //#endregion
 //#region src/index.d.ts
@@ -433,5 +472,5 @@ declare class LaminarClient {
   get traces(): TracesResource;
 }
 //#endregion
-export { LaminarClient };
+export { type CacheOutcome, LaminarClient, RolloutSessionsResource };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, RolloutParam, SpanType, StringUUID } from "@lmnr-ai/types";
+import { CachedSpan, Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, StringUUID } from "@lmnr-ai/types";
 
 //#region src/resources/index.d.ts
 declare class BaseResource {
@@ -257,49 +257,83 @@ declare class EvaluatorsResource extends BaseResource {
 }
 //#endregion
 //#region src/resources/rollout-sessions.d.ts
+/**
+ * Result of a debug-replay cache lookup (debug-replay v2).
+ *
+ *  - `hit`  — the server served a cached response for this input hash; replay it
+ *             and mark the span CACHED.
+ *  - `miss` — no cache entry; the caller latches process-wide live mode and runs
+ *             every subsequent call live.
+ *  - `live` — run THIS call live without latching (server COLD warmup-timeout
+ *             degrade, or any non-OK / transport error here).
+ */
+type CacheOutcome = {
+  kind: "hit";
+  cached: CachedSpan;
+} | {
+  kind: "miss";
+} | {
+  kind: "live";
+};
 declare class RolloutSessionsResource extends BaseResource {
   constructor(baseHttpUrl: string, projectApiKey: string);
   /**
-   * Connects to the SSE stream for rollout debugging sessions
-   * Returns the Response object for streaming SSE events
+   * Idempotently register (upsert) a debug session on the backend, keyed on the
+   * SDK-supplied session id. The backend stores the row so the session is
+   * visible in the UI; a null/omitted name never clobbers a name set elsewhere.
+   *
+   * Returns the backend-resolved `projectId` (derived from the API key) so the
+   * caller can build the debugger URL; null if the body can't be parsed.
    */
-  connect({
+  register({
     sessionId,
-    name,
-    params,
-    signal
+    name
   }: {
     sessionId: string;
-    params: RolloutParam[];
-    name: string;
-    signal?: AbortSignal;
-  }): Promise<Response>;
-  delete({
-    sessionId
+    name?: string;
+  }): Promise<string | null>;
+  /**
+   * Rename an existing debug session. Update-only: the backend returns 404 (and
+   * this throws) when the session id is unknown for the project, so a mistyped
+   * id surfaces as an error rather than silently creating a session. Creation
+   * stays the SDK's job via {@link register}.
+   */
+  setName({
+    sessionId,
+    name
   }: {
     sessionId: string;
+    name: string;
   }): Promise<void>;
-  setStatus({
+  /**
+   * Look up the debug-replay cache for a single LLM call (debug-replay v2).
+   *
+   * The server is keyed by `inputHash` (hex blake3 of the canonicalized,
+   * system-stripped input messages). It returns one of three outcomes:
+   *   - `{ outcome: "hit", response }` — a cached response to replay.
+   *   - `{ outcome: "miss" }`          — no entry; caller latches live mode.
+   *   - `{ outcome: "live" }`          — run this call live (COLD degrade).
+   *
+   * Error posture: a non-OK response or a transport error degrades to
+   * `{ kind: "live" }` for THIS call only — it never throws and never latches
+   * the process-wide live flag (only a real MISS does that). This keeps a flaky
+   * cache backend from turning a replay into a crash.
+   */
+  cache({
     sessionId,
-    status
+    replayTraceId,
+    cacheUntil,
+    inputHash
   }: {
     sessionId: string;
-    status: 'PENDING' | 'RUNNING' | 'FINISHED' | 'STOPPED';
-  }): Promise<void>;
-  sendSpanUpdate({
-    sessionId,
-    span
+    replayTraceId: string;
+    cacheUntil: string;
+    inputHash: string;
+  }): Promise<CacheOutcome>;
+  delete({
+    sessionId
   }: {
     sessionId: string;
-    span: {
-      name: string;
-      startTime: string;
-      spanId: string;
-      traceId: string;
-      parentSpanId: string | undefined;
-      attributes: Record<string, any>;
-      spanType: SpanType;
-    };
   }): Promise<void>;
 }
 //#endregion
@@ -371,13 +405,16 @@ declare class TracesResource extends BaseResource {
    *
    * A 404 response (the trace was not found in the project — typically because
    * it has not been flushed yet) is logged as a warning and the call returns
-   * without throwing; any other non-OK status throws.
+   * without throwing, since the 404 may be expected when pushing too soon
+   * after the trace run. Pass `failOnNotFound: true` to throw instead (e.g.
+   * CLI callers that must report the failure). Any other non-OK status throws.
    *
    * @param traceId - The trace id to push metadata to. Accepts a UUID string
    *   or a 32-char OTel hex trace id.
    * @param metadata - The metadata patch. Top-level keys are merged into the
    *   trace's existing metadata. Must be non-empty (the server rejects empty
    *   patches with 400).
+   * @param options - `failOnNotFound`: throw on 404 instead of warn-and-return.
    * @example
    * ```typescript
    * import { Laminar, observe, LaminarClient } from "@lmnr-ai/lmnr";
@@ -399,7 +436,9 @@ declare class TracesResource extends BaseResource {
    * }
    * ```
    */
-  pushMetadata(traceId: string, metadata: Record<string, unknown>): Promise<void>;
+  pushMetadata(traceId: string, metadata: Record<string, unknown>, options?: {
+    failOnNotFound?: boolean;
+  }): Promise<void>;
 }
 //#endregion
 //#region src/index.d.ts
@@ -433,5 +472,5 @@ declare class LaminarClient {
   get traces(): TracesResource;
 }
 //#endregion
-export { LaminarClient };
+export { type CacheOutcome, LaminarClient, RolloutSessionsResource };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -3,8 +3,9 @@ import * as path from "path";
 import pino from "pino";
 import { PinoPretty } from "pino-pretty";
 import { v4 } from "uuid";
+import { errorMessage } from "@lmnr-ai/types";
 //#region package.json
-var version = "0.8.26";
+var version = "0.8.28";
 //#endregion
 //#region src/version.ts
 function getLangVersion() {
@@ -69,7 +70,7 @@ function initializeLogger(options) {
 		minimumLevel: level
 	}));
 }
-const logger$3 = initializeLogger();
+const logger$4 = initializeLogger();
 const isStringUUID = (id) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id);
 const newUUID = () => {
 	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
@@ -78,9 +79,9 @@ const newUUID = () => {
 const otelSpanIdToUUID = (spanId) => {
 	let id = spanId.toLowerCase();
 	if (id.startsWith("0x")) id = id.slice(2);
-	if (id.length !== 16) logger$3.warn(`Span ID ${spanId} is not 16 hex chars long. This is not a valid OpenTelemetry span ID.`);
+	if (id.length !== 16) logger$4.warn(`Span ID ${spanId} is not 16 hex chars long. This is not a valid OpenTelemetry span ID.`);
 	if (!/^[0-9a-f]+$/.test(id)) {
-		logger$3.error(`Span ID ${spanId} is not a valid hex string. Generating a random UUID instead.`);
+		logger$4.error(`Span ID ${spanId} is not a valid hex string. Generating a random UUID instead.`);
 		return newUUID();
 	}
 	return id.padStart(32, "0").replace(/^([0-9a-f]{8})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{12})$/, "$1-$2-$3-$4-$5");
@@ -88,9 +89,9 @@ const otelSpanIdToUUID = (spanId) => {
 const otelTraceIdToUUID = (traceId) => {
 	let id = traceId.toLowerCase();
 	if (id.startsWith("0x")) id = id.slice(2);
-	if (id.length !== 32) logger$3.warn(`Trace ID ${traceId} is not 32 hex chars long. This is not a valid OpenTelemetry trace ID.`);
+	if (id.length !== 32) logger$4.warn(`Trace ID ${traceId} is not 32 hex chars long. This is not a valid OpenTelemetry trace ID.`);
 	if (!/^[0-9a-f]+$/.test(id)) {
-		logger$3.error(`Trace ID ${traceId} is not a valid hex string. Generating a random UUID instead.`);
+		logger$4.error(`Trace ID ${traceId} is not a valid hex string. Generating a random UUID instead.`);
 		return newUUID();
 	}
 	return id.replace(/^([0-9a-f]{8})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{12})$/, "$1-$2-$3-$4-$5");
@@ -120,7 +121,7 @@ const loadEnv = (options) => {
 };
 //#endregion
 //#region src/resources/datasets.ts
-const logger$2 = initializeLogger();
+const logger$3 = initializeLogger();
 const DEFAULT_DATASET_PULL_LIMIT = 100;
 const DEFAULT_DATASET_PUSH_BATCH_SIZE = 100;
 var DatasetsResource = class extends BaseResource {
@@ -175,7 +176,7 @@ var DatasetsResource = class extends BaseResource {
 		let response;
 		for (let i = 0; i < points.length; i += batchSize) {
 			const batchNum = Math.floor(i / batchSize) + 1;
-			logger$2.debug(`Pushing batch ${batchNum} of ${totalBatches}`);
+			logger$3.debug(`Pushing batch ${batchNum} of ${totalBatches}`);
 			const batch = points.slice(i, i + batchSize);
 			const fetchResponse = await fetch(this.baseHttpUrl + "/v1/datasets/datapoints", {
 				method: "POST",
@@ -225,7 +226,7 @@ var DatasetsResource = class extends BaseResource {
 };
 //#endregion
 //#region src/resources/evals.ts
-const logger$1 = initializeLogger();
+const logger$2 = initializeLogger();
 const INITIAL_EVALUATION_DATAPOINT_MAX_DATA_LENGTH = 16e6;
 var EvalsResource = class extends BaseResource {
 	constructor(baseHttpUrl, projectApiKey) {
@@ -361,7 +362,7 @@ var EvalsResource = class extends BaseResource {
 	* @returns {Promise<GetDatapointsResponse>} Response from the datapoint retrieval
 	*/
 	async getDatapoints({ datasetName, offset, limit }) {
-		logger$1.warn("evals.getDatapoints() is deprecated. Use client.datasets.pull() instead.");
+		logger$2.warn("evals.getDatapoints() is deprecated. Use client.datasets.pull() instead.");
 		const params = new URLSearchParams({
 			name: datasetName,
 			offset: offset.toString(),
@@ -378,7 +379,7 @@ var EvalsResource = class extends BaseResource {
 		let length = initialLength;
 		let lastResponse = null;
 		for (let i = 0; i < maxRetries; i++) {
-			logger$1.debug(`Retrying save datapoints... ${i + 1} of ${maxRetries}, length: ${length}`);
+			logger$2.debug(`Retrying save datapoints... ${i + 1} of ${maxRetries}, length: ${length}`);
 			const response = await fetch(this.baseHttpUrl + `/v1/evals/${evalId}/datapoints`, {
 				method: "POST",
 				headers: this.headers(),
@@ -464,60 +465,129 @@ var EvaluatorsResource = class extends BaseResource {
 };
 //#endregion
 //#region src/resources/rollout-sessions.ts
+const logger$1 = initializeLogger();
+/**
+* Map the opaque HIT `response` payload onto a {@link CachedSpan} the provider
+* wrappers can replay. The server-side shape of `response` is not yet frozen
+* (app-server plan 01 leaves it as a `serde_json::Value`), so this stays
+* deliberately tolerant: the whole payload is serialized into `output` (the only
+* field the AI SDK wrapper's `parseCachedSpan` actually reads, via
+* `JSON.parse`), and a `finishReason` is surfaced into `attributes` when the
+* payload carries one. `name`/`input` are irrelevant to replay and left empty.
+*/
+const toCachedSpan = (response) => {
+	const output = typeof response === "string" ? response : JSON.stringify(response ?? null);
+	const attributes = {};
+	if (response !== null && typeof response === "object" && typeof response.finishReason === "string") attributes["ai.response.finishReason"] = response.finishReason;
+	return {
+		name: "",
+		input: "",
+		output,
+		attributes
+	};
+};
 var RolloutSessionsResource = class extends BaseResource {
 	constructor(baseHttpUrl, projectApiKey) {
 		super(baseHttpUrl, projectApiKey);
 	}
 	/**
-	* Connects to the SSE stream for rollout debugging sessions
-	* Returns the Response object for streaming SSE events
+	* Idempotently register (upsert) a debug session on the backend, keyed on the
+	* SDK-supplied session id. The backend stores the row so the session is
+	* visible in the UI; a null/omitted name never clobbers a name set elsewhere.
+	*
+	* Returns the backend-resolved `projectId` (derived from the API key) so the
+	* caller can build the debugger URL; null if the body can't be parsed.
 	*/
-	async connect({ sessionId, name, params, signal }) {
+	async register({ sessionId, name }) {
 		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
 			method: "POST",
-			headers: {
-				...this.headers(),
-				"Accept": "text/event-stream"
-			},
-			body: JSON.stringify({
-				name,
-				params
-			}),
-			signal
-		});
-		if (!response.ok) throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
-		if (!response.body) throw new Error("No response body");
-		return response;
-	}
-	async delete({ sessionId }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
-			method: "DELETE",
-			headers: this.headers()
+			headers: this.headers(),
+			body: JSON.stringify({ name })
 		});
 		if (!response.ok) await this.handleError(response);
+		try {
+			return (await response.json()).projectId ?? null;
+		} catch (e) {
+			logger$1.warn(`Failed to parse rollout register response: ${errorMessage(e)}`);
+			return null;
+		}
 	}
-	async setStatus({ sessionId, status }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/status`, {
+	/**
+	* Rename an existing debug session. Update-only: the backend returns 404 (and
+	* this throws) when the session id is unknown for the project, so a mistyped
+	* id surfaces as an error rather than silently creating a session. Creation
+	* stays the SDK's job via {@link register}.
+	*/
+	async setName({ sessionId, name }) {
+		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/name`, {
 			method: "PATCH",
 			headers: this.headers(),
-			body: JSON.stringify({ status })
+			body: JSON.stringify({ name })
 		});
 		if (!response.ok) await this.handleError(response);
 	}
-	async sendSpanUpdate({ sessionId, span }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/update`, {
-			method: "PATCH",
-			headers: this.headers(),
-			body: JSON.stringify({
-				type: "spanStart",
-				spanId: otelSpanIdToUUID(span.spanId),
-				traceId: otelTraceIdToUUID(span.traceId),
-				parentSpanId: span.parentSpanId ? otelSpanIdToUUID(span.parentSpanId) : void 0,
-				attributes: span.attributes,
-				startTime: span.startTime,
-				name: span.name,
-				spanType: span.spanType
-			})
+	/**
+	* Look up the debug-replay cache for a single LLM call (debug-replay v2).
+	*
+	* The server is keyed by `inputHash` (hex blake3 of the canonicalized,
+	* system-stripped input messages). It returns one of three outcomes:
+	*   - `{ outcome: "hit", response }` — a cached response to replay.
+	*   - `{ outcome: "miss" }`          — no entry; caller latches live mode.
+	*   - `{ outcome: "live" }`          — run this call live (COLD degrade).
+	*
+	* Error posture: a non-OK response or a transport error degrades to
+	* `{ kind: "live" }` for THIS call only — it never throws and never latches
+	* the process-wide live flag (only a real MISS does that). This keeps a flaky
+	* cache backend from turning a replay into a crash.
+	*/
+	async cache({ sessionId, replayTraceId, cacheUntil, inputHash }) {
+		let response;
+		try {
+			response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/cache`, {
+				method: "POST",
+				headers: this.headers(),
+				body: JSON.stringify({
+					replayTraceId,
+					cacheUntil,
+					inputHash
+				})
+			});
+		} catch (e) {
+			logger$1.warn(`Debug cache lookup failed, running live: ${errorMessage(e)}`);
+			return { kind: "live" };
+		}
+		if (!response.ok) {
+			logger$1.warn(`Debug cache lookup returned ${response.status}, running live`);
+			return { kind: "live" };
+		}
+		let body;
+		try {
+			body = await response.json();
+		} catch (e) {
+			logger$1.warn(`Failed to parse debug cache response, running live: ${errorMessage(e)}`);
+			return { kind: "live" };
+		}
+		switch (body.outcome) {
+			case "hit":
+				if (body.response === null || body.response === void 0) {
+					logger$1.warn("Debug cache HIT had no response payload, running live");
+					return { kind: "live" };
+				}
+				return {
+					kind: "hit",
+					cached: toCachedSpan(body.response)
+				};
+			case "miss": return { kind: "miss" };
+			case "live": return { kind: "live" };
+			default:
+				logger$1.warn(`Unknown debug cache outcome "${body.outcome}", running live`);
+				return { kind: "live" };
+		}
+	}
+	async delete({ sessionId }) {
+		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
+			method: "DELETE",
+			headers: this.headers()
 		});
 		if (!response.ok) await this.handleError(response);
 	}
@@ -626,13 +696,16 @@ var TracesResource = class extends BaseResource {
 	*
 	* A 404 response (the trace was not found in the project — typically because
 	* it has not been flushed yet) is logged as a warning and the call returns
-	* without throwing; any other non-OK status throws.
+	* without throwing, since the 404 may be expected when pushing too soon
+	* after the trace run. Pass `failOnNotFound: true` to throw instead (e.g.
+	* CLI callers that must report the failure). Any other non-OK status throws.
 	*
 	* @param traceId - The trace id to push metadata to. Accepts a UUID string
 	*   or a 32-char OTel hex trace id.
 	* @param metadata - The metadata patch. Top-level keys are merged into the
 	*   trace's existing metadata. Must be non-empty (the server rejects empty
 	*   patches with 400).
+	* @param options - `failOnNotFound`: throw on 404 instead of warn-and-return.
 	* @example
 	* ```typescript
 	* import { Laminar, observe, LaminarClient } from "@lmnr-ai/lmnr";
@@ -654,7 +727,7 @@ var TracesResource = class extends BaseResource {
 	* }
 	* ```
 	*/
-	async pushMetadata(traceId, metadata) {
+	async pushMetadata(traceId, metadata, options) {
 		if (!metadata || Object.keys(metadata).length === 0) throw new Error("metadata must be a non-empty object");
 		const formattedTraceId = isStringUUID(traceId) ? traceId : otelTraceIdToUUID(traceId);
 		const url = this.baseHttpUrl + "/v1/traces/metadata";
@@ -667,7 +740,9 @@ var TracesResource = class extends BaseResource {
 			})
 		});
 		if (response.status === 404) {
-			logger.warn(`Trace ${formattedTraceId} not found. The trace may not have been flushed yet — call await Laminar.flush() and retry.`);
+			const message = `Trace ${formattedTraceId} not found. The trace may not have been flushed yet — call await Laminar.flush() and retry.`;
+			if (options?.failOnNotFound) throw new Error(message);
+			logger.warn(message);
 			return;
 		}
 		if (!response.ok) await this.handleError(response);
@@ -717,6 +792,6 @@ var LaminarClient = class {
 	}
 };
 //#endregion
-export { LaminarClient };
+export { LaminarClient, RolloutSessionsResource };
 
 //# sourceMappingURL=index.mjs.map