lmnr-cli 0.1.9 → 0.1.10

package/dist/index.cjs

@@ -6,7 +6,7 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -25,11 +25,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let commander = require("commander");
 let fs = require("fs");
 let path = require("path");
+let path$2 = __toESM(path, 1);
 path = __toESM(path);
 let pino = require("pino");
+let pino$3 = __toESM(pino, 1);
 pino = __toESM(pino);
 let pino_pretty = require("pino-pretty");
-let uuid = require("uuid");
 let csv_parser = require("csv-parser");
 csv_parser = __toESM(csv_parser);
 let export_to_csv = require("export-to-csv");
@@ -37,104 +38,27 @@ let fs_promises = require("fs/promises");
 fs_promises = __toESM(fs_promises);
 let cli_table3 = require("cli-table3");
 cli_table3 = __toESM(cli_table3);
-let chokidar = require("chokidar");
-chokidar = __toESM(chokidar);
-let http = require("http");
-http = __toESM(http);
-let events = require("events");
-let eventsource_parser = require("eventsource-parser");
-let child_process = require("child_process");
-let readline = require("readline");
-readline = __toESM(readline);
-//#region package.json
-var version$1 = "0.1.9";
+//#region ../types/dist/index.mjs
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
-//#region ../../node_modules/.pnpm/dotenv@17.2.3/node_modules/dotenv/package.json
-var require_package = /* @__PURE__ */ __commonJSMin(((exports, module) => {
-	module.exports = {
-		"name": "dotenv",
-		"version": "17.2.3",
-		"description": "Loads environment variables from .env file",
-		"main": "lib/main.js",
-		"types": "lib/main.d.ts",
-		"exports": {
-			".": {
-				"types": "./lib/main.d.ts",
-				"require": "./lib/main.js",
-				"default": "./lib/main.js"
-			},
-			"./config": "./config.js",
-			"./config.js": "./config.js",
-			"./lib/env-options": "./lib/env-options.js",
-			"./lib/env-options.js": "./lib/env-options.js",
-			"./lib/cli-options": "./lib/cli-options.js",
-			"./lib/cli-options.js": "./lib/cli-options.js",
-			"./package.json": "./package.json"
-		},
-		"scripts": {
-			"dts-check": "tsc --project tests/types/tsconfig.json",
-			"lint": "standard",
-			"pretest": "npm run lint && npm run dts-check",
-			"test": "tap run tests/**/*.js --allow-empty-coverage --disable-coverage --timeout=60000",
-			"test:coverage": "tap run tests/**/*.js --show-full-coverage --timeout=60000 --coverage-report=text --coverage-report=lcov",
-			"prerelease": "npm test",
-			"release": "standard-version"
-		},
-		"repository": {
-			"type": "git",
-			"url": "git://github.com/motdotla/dotenv.git"
-		},
-		"homepage": "https://github.com/motdotla/dotenv#readme",
-		"funding": "https://dotenvx.com",
-		"keywords": [
-			"dotenv",
-			"env",
-			".env",
-			"environment",
-			"variables",
-			"config",
-			"settings"
-		],
-		"readmeFilename": "README.md",
-		"license": "BSD-2-Clause",
-		"devDependencies": {
-			"@types/node": "^18.11.3",
-			"decache": "^4.6.2",
-			"sinon": "^14.0.1",
-			"standard": "^17.0.0",
-			"standard-version": "^9.5.0",
-			"tap": "^19.2.0",
-			"typescript": "^4.8.4"
-		},
-		"engines": { "node": ">=12" },
-		"browser": { "fs": false }
-	};
-}));
+//#region package.json
+var version$1 = "0.1.10";
 //#endregion
-//#region ../client/dist/index.mjs
-var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+//#region ../../node_modules/.pnpm/dotenv@17.4.2/node_modules/dotenv/lib/main.js
+var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const fs$1 = require("fs");
 	const path$1 = require("path");
 	const os = require("os");
 	const crypto$1 = require("crypto");
-	const version = require_package().version;
 	const TIPS = [
-		"🔐 encrypt with Dotenvx: https://dotenvx.com",
-		"🔐 prevent committing .env to code: https://dotenvx.com/precommit",
-		"🔐 prevent building .env in docker: https://dotenvx.com/prebuild",
-		"📡 add observability to secrets: https://dotenvx.com/ops",
-		"👥 sync secrets across teammates & machines: https://dotenvx.com/ops",
-		"🗂️ backup and recover secrets: https://dotenvx.com/ops",
-		"✅ audit secrets and track compliance: https://dotenvx.com/ops",
-		"🔄 add secrets lifecycle management: https://dotenvx.com/ops",
-		"🔑 add access controls to secrets: https://dotenvx.com/ops",
-		"🛠️  run anywhere with `dotenvx run -- yourcommand`",
-		"⚙️  specify custom .env file path with { path: '/custom/path/.env' }",
-		"⚙️  enable debug logging with { debug: true }",
-		"⚙️  override existing env vars with { override: true }",
-		"⚙️  suppress all logs with { quiet: true }",
-		"⚙️  write to custom object with { processEnv: myObject }",
-		"⚙️  load multiple .env files with { path: ['.env.local', '.env'] }"
+		"◈ encrypted .env [www.dotenvx.com]",
+		"◈ secrets for agents [www.dotenvx.com]",
+		"⌁ auth for agents [www.vestauth.com]",
+		"⌘ custom filepath { path: '/custom/path/.env' }",
+		"⌘ enable debugging { debug: true }",
+		"⌘ override existing { override: true }",
+		"⌘ suppress logs { quiet: true }",
+		"⌘ multiple files { path: ['.env.local', '.env'] }"
 	];
 	function _getRandomTip() {
 		return TIPS[Math.floor(Math.random() * TIPS.length)];
@@ -198,13 +122,13 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		return DotenvModule.parse(decrypted);
 	}
 	function _warn(message) {
-		console.error(`[dotenv@${version}][WARN] ${message}`);
+		console.error(`⚠ ${message}`);
 	}
 	function _debug(message) {
-		console.log(`[dotenv@${version}][DEBUG] ${message}`);
+		console.log(`┆ ${message}`);
 	}
 	function _log(message) {
-		console.log(`[dotenv@${version}] ${message}`);
+		console.log(`◇ ${message}`);
 	}
 	function _dotenvKey(options) {
 		if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) return options.DOTENV_KEY;
@@ -262,7 +186,7 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	function _configVault(options) {
 		const debug = parseBoolean(process.env.DOTENV_CONFIG_DEBUG || options && options.debug);
 		const quiet = parseBoolean(process.env.DOTENV_CONFIG_QUIET || options && options.quiet);
-		if (debug || !quiet) _log("Loading env from encrypted .env.vault");
+		if (debug || !quiet) _log("loading env from encrypted .env.vault");
 		const parsed = DotenvModule._parseVault(options);
 		let processEnv = process.env;
 		if (options && options.processEnv != null) processEnv = options.processEnv;
@@ -277,7 +201,7 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		let debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || options && options.debug);
 		let quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || options && options.quiet);
 		if (options && options.encoding) encoding = options.encoding;
-		else if (debug) _debug("No encoding is specified. UTF-8 is used by default");
+		else if (debug) _debug("no encoding is specified (UTF-8 is used by default)");
 		let optionPaths = [dotenvPath];
 		if (options && options.path) if (!Array.isArray(options.path)) optionPaths = [_resolveHome(options.path)];
 		else {
@@ -286,11 +210,11 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		}
 		let lastError;
 		const parsedAll = {};
-		for (const path$5 of optionPaths) try {
-			const parsed = DotenvModule.parse(fs$1.readFileSync(path$5, { encoding }));
+		for (const path$3 of optionPaths) try {
+			const parsed = DotenvModule.parse(fs$1.readFileSync(path$3, { encoding }));
 			DotenvModule.populate(parsedAll, parsed, options);
 		} catch (e) {
-			if (debug) _debug(`Failed to load ${path$5} ${e.message}`);
+			if (debug) _debug(`failed to load ${path$3} ${e.message}`);
 			lastError = e;
 		}
 		const populated = DotenvModule.populate(processEnv, parsedAll, options);
@@ -303,10 +227,10 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 				const relative = path$1.relative(process.cwd(), filePath);
 				shortPaths.push(relative);
 			} catch (e) {
-				if (debug) _debug(`Failed to load ${filePath} ${e.message}`);
+				if (debug) _debug(`failed to load ${filePath} ${e.message}`);
 				lastError = e;
 			}
-			_log(`injecting env (${keysCount}) from ${shortPaths.join(",")} ${dim(`-- tip: ${_getRandomTip()}`)}`);
+			_log(`injected env (${keysCount}) from ${shortPaths.join(",")} ${dim(`// tip: ${_getRandomTip()}`)}`);
 		}
 		if (lastError) return {
 			parsed: parsedAll,
@@ -318,7 +242,7 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		if (_dotenvKey(options).length === 0) return DotenvModule.configDotenv(options);
 		const vaultPath = _vaultPath(options);
 		if (!vaultPath) {
-			_warn(`You set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}. Did you forget to build it?`);
+			_warn(`you set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}`);
 			return DotenvModule.configDotenv(options);
 		}
 		return DotenvModule._configVault(options);
@@ -387,8 +311,44 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports.parse = DotenvModule.parse;
 	module.exports.populate = DotenvModule.populate;
 	module.exports = DotenvModule;
-})))();
-var version = "0.8.18";
+}));
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/stringify.js
+const byteToHex = [];
+for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
+function unsafeStringify(arr, offset = 0) {
+	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/rng.js
+const rnds8 = new Uint8Array(16);
+function rng() {
+	return crypto.getRandomValues(rnds8);
+}
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/v4.js
+function v4(options, buf, offset) {
+	if (!buf && !options && crypto.randomUUID) return crypto.randomUUID();
+	return _v4(options, buf, offset);
+}
+function _v4(options, buf, offset) {
+	options = options || {};
+	const rnds = options.random ?? options.rng?.() ?? rng();
+	if (rnds.length < 16) throw new Error("Random bytes length must be >= 16");
+	rnds[6] = rnds[6] & 15 | 64;
+	rnds[8] = rnds[8] & 63 | 128;
+	if (buf) {
+		offset = offset || 0;
+		if (offset < 0 || offset + 16 > buf.length) throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+		for (let i = 0; i < 16; ++i) buf[offset + i] = rnds[i];
+		return buf;
+	}
+	return unsafeStringify(rnds);
+}
+//#endregion
+//#region ../client/dist/index.mjs
+var import_main = require_main();
+var version = "0.8.27";
 function getLangVersion() {
 	if (typeof process !== "undefined" && process.versions && process.versions.node) return `node-${process.versions.node}`;
 	if (typeof navigator !== "undefined" && navigator.userAgent) return `browser-${navigator.userAgent}`;
@@ -440,34 +400,34 @@ var BrowserEventsResource = class extends BaseResource {
 function initializeLogger$1(options) {
 	const colorize = options?.colorize ?? true;
 	const level = options?.level ?? process.env.LMNR_LOG_LEVEL?.toLowerCase()?.trim() ?? "info";
-	return (0, pino.default)({ level }, (0, pino_pretty.PinoPretty)({
+	return (0, pino$3.default)({ level }, (0, pino_pretty.PinoPretty)({
 		colorize,
 		minimumLevel: level
 	}));
 }
-const logger$2$1 = initializeLogger$1();
+const logger$4$1 = initializeLogger$1();
 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$1 = () => {
+const newUUID = () => {
 	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
-	else return (0, uuid.v4)();
+	else return v4();
 };
 const otelSpanIdToUUID = (spanId) => {
 	let id = spanId.toLowerCase();
 	if (id.startsWith("0x")) id = id.slice(2);
-	if (id.length !== 16) logger$2$1.warn(`Span ID ${spanId} is not 16 hex chars long. This is not a valid OpenTelemetry span ID.`);
+	if (id.length !== 16) logger$4$1.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$2$1.error(`Span ID ${spanId} is not a valid hex string. Generating a random UUID instead.`);
-		return newUUID$1();
+		logger$4$1.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");
 };
 const otelTraceIdToUUID = (traceId) => {
 	let id = traceId.toLowerCase();
 	if (id.startsWith("0x")) id = id.slice(2);
-	if (id.length !== 32) logger$2$1.warn(`Trace ID ${traceId} is not 32 hex chars long. This is not a valid OpenTelemetry trace ID.`);
+	if (id.length !== 32) logger$4$1.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$2$1.error(`Trace ID ${traceId} is not a valid hex string. Generating a random UUID instead.`);
-		return newUUID$1();
+		logger$4$1.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");
 };
@@ -490,11 +450,11 @@ const loadEnv = (options) => {
 	const verbose = ["debug", "trace"].includes(logLevel.trim().toLowerCase());
 	const quiet = options?.quiet ?? !verbose;
 	(0, import_main.config)({
-		path: options?.paths ?? envFiles.map((envFile) => path.resolve(envDir, envFile)),
+		path: options?.paths ?? envFiles.map((envFile) => path$2.resolve(envDir, envFile)),
 		quiet
 	});
 };
-const logger$1$1 = initializeLogger$1();
+const logger$3$1 = initializeLogger$1();
 const DEFAULT_DATASET_PULL_LIMIT = 100;
 const DEFAULT_DATASET_PUSH_BATCH_SIZE$1 = 100;
 var DatasetsResource = class extends BaseResource {
@@ -549,7 +509,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$1$1.debug(`Pushing batch ${batchNum} of ${totalBatches}`);
+			logger$3$1.debug(`Pushing batch ${batchNum} of ${totalBatches}`);
 			const batch = points.slice(i, i + batchSize);
 			const fetchResponse = await fetch(this.baseHttpUrl + "/v1/datasets/datapoints", {
 				method: "POST",
@@ -597,7 +557,7 @@ var DatasetsResource = class extends BaseResource {
 		return response.json();
 	}
 };
-const logger$6 = initializeLogger$1();
+const logger$2$1 = initializeLogger$1();
 const INITIAL_EVALUATION_DATAPOINT_MAX_DATA_LENGTH = 16e6;
 var EvalsResource = class extends BaseResource {
 	constructor(baseHttpUrl, projectApiKey) {
@@ -655,14 +615,14 @@ var EvalsResource = class extends BaseResource {
 	* @returns {Promise<StringUUID>} The datapoint ID
 	*/
 	async createDatapoint({ evalId, data, target, metadata, index, traceId }) {
-		const datapointId = newUUID$1();
+		const datapointId = newUUID();
 		const partialDatapoint = {
 			id: datapointId,
 			data,
 			target,
 			index: index ?? 0,
-			traceId: traceId ?? newUUID$1(),
-			executorSpanId: newUUID$1(),
+			traceId: traceId ?? newUUID(),
+			executorSpanId: newUUID(),
 			metadata
 		};
 		await this.saveDatapoints({
@@ -733,7 +693,7 @@ var EvalsResource = class extends BaseResource {
 	* @returns {Promise<GetDatapointsResponse>} Response from the datapoint retrieval
 	*/
 	async getDatapoints({ datasetName, offset, limit }) {
-		logger$6.warn("evals.getDatapoints() is deprecated. Use client.datasets.pull() instead.");
+		logger$2$1.warn("evals.getDatapoints() is deprecated. Use client.datasets.pull() instead.");
 		const params = new URLSearchParams({
 			name: datasetName,
 			offset: offset.toString(),
@@ -750,7 +710,7 @@ var EvalsResource = class extends BaseResource {
 		let length = initialLength;
 		let lastResponse = null;
 		for (let i = 0; i < maxRetries; i++) {
-			logger$6.debug(`Retrying save datapoints... ${i + 1} of ${maxRetries}, length: ${length}`);
+			logger$2$1.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(),
@@ -771,11 +731,6 @@ var EvalsResource = class extends BaseResource {
 		if (lastResponse && !lastResponse.ok) await this.handleError(lastResponse);
 	}
 };
-var EvaluatorScoreSourceType = /* @__PURE__ */ function(EvaluatorScoreSourceType) {
-	EvaluatorScoreSourceType["Evaluator"] = "Evaluator";
-	EvaluatorScoreSourceType["Code"] = "Code";
-	return EvaluatorScoreSourceType;
-}(EvaluatorScoreSourceType || {});
 /**
 * Resource for creating evaluator scores
 */
@@ -814,25 +769,21 @@ var EvaluatorsResource = class extends BaseResource {
 	async score(options) {
 		const { name, metadata, score } = options;
 		let payload;
-		if ("traceId" in options && options.traceId) {
-			const formattedTraceId = isStringUUID(options.traceId) ? options.traceId : otelTraceIdToUUID(options.traceId);
-			payload = {
-				name,
-				metadata,
-				score,
-				source: EvaluatorScoreSourceType.Code,
-				traceId: formattedTraceId
-			};
-		} else if ("spanId" in options && options.spanId) {
-			const formattedSpanId = isStringUUID(options.spanId) ? options.spanId : otelSpanIdToUUID(options.spanId);
-			payload = {
-				name,
-				metadata,
-				score,
-				source: EvaluatorScoreSourceType.Code,
-				spanId: formattedSpanId
-			};
-		} else throw new Error("Either 'traceId' or 'spanId' must be provided.");
+		if ("traceId" in options && options.traceId) payload = {
+			name,
+			metadata,
+			score,
+			source: "Code",
+			traceId: isStringUUID(options.traceId) ? options.traceId : otelTraceIdToUUID(options.traceId)
+		};
+		else if ("spanId" in options && options.spanId) payload = {
+			name,
+			metadata,
+			score,
+			source: "Code",
+			spanId: isStringUUID(options.spanId) ? options.spanId : otelSpanIdToUUID(options.spanId)
+		};
+		else throw new Error("Either 'traceId' or 'spanId' must be provided.");
 		const response = await fetch(this.baseHttpUrl + "/v1/evaluators/score", {
 			method: "POST",
 			headers: this.headers(),
@@ -841,60 +792,51 @@ var EvaluatorsResource = class extends BaseResource {
 		if (!response.ok) await this.handleError(response);
 	}
 };
+const logger$1$1 = initializeLogger$1();
 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$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
-			})
+	async delete({ sessionId }) {
+		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
+			method: "DELETE",
+			headers: this.headers()
 		});
 		if (!response.ok) await this.handleError(response);
 	}
@@ -971,12 +913,91 @@ var TagsResource = class extends BaseResource {
 		return response.json();
 	}
 };
+/** Resource for post-factum operations on existing traces. */
+const logger$5 = initializeLogger$1();
+var TracesResource = class extends BaseResource {
+	/** Resource for post-factum operations on existing traces. */
+	constructor(baseHttpUrl, projectApiKey) {
+		super(baseHttpUrl, projectApiKey);
+	}
+	/**
+	* Push a metadata patch to an existing trace.
+	*
+	* The patch is shallow-merged server-side into the trace's existing metadata
+	* (`existing || patch`, last-write-wins per top-level key). Useful for
+	* attaching post-factum signals — quality scores, human edits, triage labels —
+	* to a trace that has already finished. The patch does NOT extend `endTime`
+	* or change tokens / cost / top span / tags / span names. `numSpans` is
+	* incremented by 1 (paid by the virtual span that carried the patch through
+	* the ingestion queue) so the new ClickHouse row beats the prior version on
+	* `ReplacingMergeTree(numSpans)`. No row is added to the `spans` table.
+	*
+	* Compared to `Laminar.setTraceMetadata` (which sets metadata on the
+	* currently in-flight trace via OpenTelemetry attributes), this method
+	* operates on a finished trace by trace id, so it must be called after the
+	* trace has been flushed.
+	*
+	* 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, 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";
+	* Laminar.initialize();
+	* const client = new LaminarClient();
+	*
+	* let traceId: string | null = null;
+	* await observe({ name: "generate" }, async () => {
+	*   traceId = await Laminar.getTraceId();
+	* });
+	* await Laminar.flush();
+	*
+	* if (traceId) {
+	*   await client.traces.pushMetadata(traceId, {
+	*     score: 0.85,
+	*     reviewer: "alice",
+	*     needsReview: false,
+	*   });
+	* }
+	* ```
+	*/
+	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";
+		const response = await fetch(url, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify({
+				traceId: formattedTraceId,
+				metadata
+			})
+		});
+		if (response.status === 404) {
+			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$5.warn(message);
+			return;
+		}
+		if (!response.ok) await this.handleError(response);
+	}
+};
 var LaminarClient = class {
 	constructor({ baseUrl, projectApiKey, port } = {}) {
 		loadEnv();
 		this.projectApiKey = projectApiKey ?? process.env.LMNR_PROJECT_API_KEY;
 		const httpPort = port ?? (baseUrl?.match(/:\d{1,5}$/g) ? parseInt(baseUrl.match(/:\d{1,5}$/g)[0].slice(1)) : 443);
-		this.baseUrl = `${(baseUrl ?? process.env.LMNR_BASE_URL)?.replace(/\/$/, "").replace(/:\d{1,5}$/g, "") ?? "https://api.lmnr.ai"}:${httpPort}`;
+		const baseUrlNoPort = (baseUrl ?? process.env.LMNR_BASE_URL)?.replace(/\/$/, "").replace(/:\d{1,5}$/g, "");
+		this.baseUrl = `${baseUrlNoPort ?? "https://api.lmnr.ai"}:${httpPort}`;
 		this._browserEvents = new BrowserEventsResource(this.baseUrl, this.projectApiKey);
 		this._datasets = new DatasetsResource(this.baseUrl, this.projectApiKey);
 		this._evals = new EvalsResource(this.baseUrl, this.projectApiKey);
@@ -984,6 +1005,7 @@ var LaminarClient = class {
 		this._rolloutSessions = new RolloutSessionsResource(this.baseUrl, this.projectApiKey);
 		this._sql = new SqlResource(this.baseUrl, this.projectApiKey);
 		this._tags = new TagsResource(this.baseUrl, this.projectApiKey);
+		this._traces = new TracesResource(this.baseUrl, this.projectApiKey);
 	}
 	get browserEvents() {
 		return this._browserEvents;
@@ -1006,6 +1028,9 @@ var LaminarClient = class {
 	get tags() {
 		return this._tags;
 	}
+	get traces() {
+		return this._traces;
+	}
 };
 //#endregion
 //#region src/utils/logger.ts
@@ -1020,7 +1045,7 @@ function initializeLogger(options) {
 }
 //#endregion
 //#region src/utils/file.ts
-const logger$5 = initializeLogger();
+const logger$4 = initializeLogger();
 /**
 * Check if a file has a supported extension.
 */
@@ -1041,7 +1066,7 @@ const collectFiles = async (paths, recursive = false) => {
 	for (const filepath of paths) try {
 		const stats = await fs_promises.stat(filepath);
 		if (stats.isFile()) if (isSupportedFile(filepath)) collectedFiles.push(filepath);
-		else logger$5.warn(`Skipping unsupported file type: ${filepath}`);
+		else logger$4.warn(`Skipping unsupported file type: ${filepath}`);
 		else if (stats.isDirectory()) {
 			const entries = await fs_promises.readdir(filepath);
 			for (const entry of entries) {
@@ -1055,7 +1080,7 @@ const collectFiles = async (paths, recursive = false) => {
 			}
 		}
 	} catch (error) {
-		logger$5.warn(`Path does not exist or is not accessible: ${filepath}. Error: ${error instanceof Error ? error.message : String(error)}`);
+		logger$4.warn(`Path does not exist or is not accessible: ${filepath}. Error: ${errorMessage(error)}`);
 	}
 	return collectedFiles;
 };
@@ -1077,7 +1102,7 @@ const tryParseJson = (content) => {
 	try {
 		return JSON.parse(content);
 	} catch (error) {
-		logger$5.debug(`Error parsing JSON: ${error instanceof Error ? error.message : String(error)}`);
+		logger$4.debug(`Error parsing JSON: ${errorMessage(error)}`);
 		return content;
 	}
 };
@@ -1118,17 +1143,17 @@ async function readFile(filepath) {
 const loadFromPaths = async (paths, recursive = false) => {
 	const files = await collectFiles(paths, recursive);
 	if (files.length === 0) {
-		logger$5.warn("No supported files found in the specified paths");
+		logger$4.warn("No supported files found in the specified paths");
 		return [];
 	}
-	logger$5.info(`Found ${files.length} file(s) to read`);
+	logger$4.info(`Found ${files.length} file(s) to read`);
 	const result = [];
 	for (const file of files) try {
 		const data = await readFile(file);
 		result.push(...data);
-		logger$5.info(`Read ${data.length} record(s) from ${file}`);
+		logger$4.info(`Read ${data.length} record(s) from ${file}`);
 	} catch (error) {
-		logger$5.error(`Error reading file ${file}: ${error instanceof Error ? error.message : String(error)}`);
+		logger$4.error(`Error reading file ${file}: ${errorMessage(error)}`);
 		throw error;
 	}
 	return result;
@@ -1168,7 +1193,7 @@ const writeToFile = async (filepath, data, format) => {
 	const dir = path.dirname(filepath);
 	await fs_promises.mkdir(dir, { recursive: true });
 	const ext = format ?? path.extname(filepath).slice(1);
-	if (format && format !== path.extname(filepath).slice(1)) logger$5.warn(`Output format ${format} does not match file extension ${path.extname(filepath).slice(1)}`);
+	if (format && format !== path.extname(filepath).slice(1)) logger$4.warn(`Output format ${format} does not match file extension ${path.extname(filepath).slice(1)}`);
 	if (ext === "json") await writeJsonFile(filepath, data);
 	else if (ext === "csv") await writeCsvFile(filepath, data);
 	else if (ext === "jsonl") await writeJsonlFile(filepath, data);
@@ -1193,7 +1218,7 @@ const printToConsole = (data, format = "json") => {
 	if (format === "json") console.log(JSON.stringify(data, null, 2));
 	else if (format === "csv") {
 		if (data.length === 0) {
-			logger$5.error("No data to print");
+			logger$4.error("No data to print");
 			return;
 		}
 		console.log(formatCsv(data));
@@ -1214,7 +1239,7 @@ function outputJson(data) {
 * Use this in --json mode so agents can parse the failure.
 */
 function outputJsonError(error, exitCode = 1) {
-	console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+	console.log(JSON.stringify({ error: errorMessage(error) }));
 	process.exit(exitCode);
 }
 //#endregion
@@ -1280,7 +1305,7 @@ function renderTable(head, rows) {
 }
 //#endregion
 //#region src/commands/dataset/index.ts
-const logger$4 = initializeLogger();
+const logger$3 = initializeLogger();
 const DEFAULT_DATASET_PULL_BATCH_SIZE = 100;
 const DEFAULT_DATASET_PUSH_BATCH_SIZE = 100;
 /**
@@ -1341,7 +1366,7 @@ const handleDatasetsList = async (options) => {
 		console.log(`\nTotal: ${datasets.length} dataset(s)\n`);
 	} catch (error) {
 		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to list datasets: ${error instanceof Error ? error.message : String(error)}`);
+		logger$3.error(`Failed to list datasets: ${errorMessage(error)}`);
 		process.exit(1);
 	}
 };
@@ -1351,12 +1376,12 @@ const handleDatasetsList = async (options) => {
 const handleDatasetsPush = async (paths, options) => {
 	if (!options.name && !options.id) {
 		if (options.json) outputJsonError("Either name or id must be provided");
-		logger$4.error("Either name or id must be provided");
+		logger$3.error("Either name or id must be provided");
 		process.exit(1);
 	}
 	if (options.name && options.id) {
 		if (options.json) outputJsonError("Only one of name or id must be provided");
-		logger$4.error("Only one of name or id must be provided");
+		logger$3.error("Only one of name or id must be provided");
 		process.exit(1);
 	}
 	const client = new LaminarClient({
@@ -1368,7 +1393,7 @@ const handleDatasetsPush = async (paths, options) => {
 		const data = await loadFromPaths(paths, options.recursive);
 		if (data.length === 0) {
 			if (options.json) outputJsonError("No data to push");
-			logger$4.error("No data to push. Skipping");
+			logger$3.error("No data to push. Skipping");
 			process.exit(1);
 		}
 		const identifier = options.name ? { name: options.name } : { id: options.id };
@@ -1384,10 +1409,10 @@ const handleDatasetsPush = async (paths, options) => {
 			});
 			return;
 		}
-		logger$4.info(`Pushed ${data.length} data points to dataset ${options.name || options.id}`);
+		logger$3.info(`Pushed ${data.length} data points to dataset ${options.name || options.id}`);
 	} catch (error) {
 		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to push dataset: ${error instanceof Error ? error.message : String(error)}`);
+		logger$3.error(`Failed to push dataset: ${errorMessage(error)}`);
 		process.exit(1);
 	}
 };
@@ -1397,12 +1422,12 @@ const handleDatasetsPush = async (paths, options) => {
 const handleDatasetsPull = async (outputPath, options) => {
 	if (!options.name && !options.id) {
 		if (options.json) outputJsonError("Either name or id must be provided");
-		logger$4.error("Either name or id must be provided");
+		logger$3.error("Either name or id must be provided");
 		process.exit(1);
 	}
 	if (options.name && options.id) {
 		if (options.json) outputJsonError("Only one of name or id must be provided");
-		logger$4.error("Only one of name or id must be provided");
+		logger$3.error("Only one of name or id must be provided");
 		process.exit(1);
 	}
 	const client = new LaminarClient({
@@ -1419,12 +1444,12 @@ const handleDatasetsPull = async (outputPath, options) => {
 				path: outputPath,
 				count: result.length
 			});
-			else logger$4.info(`Successfully pulled ${result.length} data points to ${outputPath}`);
+			else logger$3.info(`Successfully pulled ${result.length} data points to ${outputPath}`);
 		} else if (options.json) outputJson(result);
 		else printToConsole(result, options.outputFormat ?? "json");
 	} catch (error) {
 		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to pull dataset: ${error instanceof Error ? error.message : String(error)}`);
+		logger$3.error(`Failed to pull dataset: ${errorMessage(error)}`);
 		process.exit(1);
 	}
 };
@@ -1441,23 +1466,23 @@ const handleDatasetsCreate = async (name, paths, options) => {
 		const data = await loadFromPaths(paths, options.recursive);
 		if (data.length === 0) {
 			if (options.json) outputJsonError("No data to push");
-			logger$4.error("No data to push. Skipping");
+			logger$3.error("No data to push. Skipping");
 			process.exit(1);
 		}
-		logger$4.info(`Pushing ${data.length} data points to dataset '${name}'...`);
+		logger$3.info(`Pushing ${data.length} data points to dataset '${name}'...`);
 		await client.datasets.push({
 			points: data,
 			name,
 			batchSize: options.batchSize ?? DEFAULT_DATASET_PUSH_BATCH_SIZE,
 			createDataset: true
 		});
-		logger$4.info(`Successfully pushed ${data.length} data points to dataset '${name}'`);
+		logger$3.info(`Successfully pushed ${data.length} data points to dataset '${name}'`);
 	} catch (error) {
 		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to create dataset: ${error instanceof Error ? error.message : String(error)}`);
+		logger$3.error(`Failed to create dataset: ${errorMessage(error)}`);
 		process.exit(1);
 	}
-	logger$4.info(`Pulling data from dataset '${name}'...`);
+	logger$3.info(`Pulling data from dataset '${name}'...`);
 	try {
 		const result = await pullAllData(client, { name }, options.batchSize ?? DEFAULT_DATASET_PULL_BATCH_SIZE, 0, void 0);
 		await writeToFile(options.outputFile, result, options.outputFormat);
@@ -1466,1058 +1491,129 @@ const handleDatasetsCreate = async (name, paths, options) => {
 			path: options.outputFile,
 			count: result.length
 		});
-		else logger$4.info(`Successfully created dataset '${name}' and saved ${result.length} datapoints to ${options.outputFile}`);
+		else logger$3.info(`Successfully created dataset '${name}' and saved ${result.length} datapoints to ${options.outputFile}`);
 	} catch (error) {
 		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to pull dataset after creation: ${error instanceof Error ? error.message : String(error)}`);
+		logger$3.error("Failed to pull dataset after creation: " + errorMessage(error));
 		process.exit(1);
 	}
 };
 //#endregion
-//#region src/cache-server.ts
-const DEFAULT_START_PORT = 35667;
+//#region src/utils/trace-note.ts
+const NOTE_METADATA_KEY = "rollout.note";
 /**
-* Finds an available port starting from the given port number
+* Normalize a user-supplied trace id (UUID or 32-char OTel hex, optionally
+* 0x-prefixed) to the dashed UUID form used by the SQL endpoint. Throws on
+* anything else so a typo fails loudly instead of querying nothing.
 */
-async function findAvailablePort(startPort) {
-	return new Promise((resolve, reject) => {
-		const server = http.createServer();
-		server.listen(startPort, () => {
-			const port = server.address().port;
-			server.close(() => resolve(port));
-		});
-		server.on("error", (err) => {
-			if (err.code === "EADDRINUSE") resolve(findAvailablePort(startPort + 1));
-			else reject(err);
-		});
-	});
-}
-/**
-* Parses request body as JSON
-*/
-function parseBody(req) {
-	return new Promise((resolve, reject) => {
-		let body = "";
-		req.on("data", (chunk) => {
-			body += chunk.toString();
-		});
-		req.on("end", () => {
-			try {
-				resolve(body ? JSON.parse(body) : {});
-			} catch (err) {
-				reject(/* @__PURE__ */ new Error(`Invalid JSON: ${err instanceof Error ? err.message : String(err)}`));
-			}
-		});
-		req.on("error", reject);
-	});
-}
-/**
-* Starts a local cache server for storing and retrieving cached LLM responses
-* during rollout debugging sessions.
-*
-* @param startPort - Optional starting port number (defaults to 35667)
-* @returns Server information including port, server instance, cache, and metadata setter
-*/
-async function startCacheServer(startPort = DEFAULT_START_PORT) {
-	const cache = /* @__PURE__ */ new Map();
-	let metadata = {
-		pathToCount: {},
-		overrides: void 0
-	};
-	const server = http.createServer((req, res) => {
-		(async () => {
-			res.setHeader("Access-Control-Allow-Origin", "*");
-			res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-			res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-			if (req.method === "OPTIONS") {
-				res.writeHead(200);
-				res.end();
-				return;
-			}
-			if (req.method === "GET" && req.url === "/health") {
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ status: "ok" }));
-				return;
-			}
-			if (req.method === "POST" && req.url === "/cached") {
-				try {
-					const { path, index } = await parseBody(req);
-					if (typeof path !== "string" || typeof index !== "number") {
-						res.writeHead(400, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "Invalid request: path (string) and index (number) required" }));
-						return;
-					}
-					const cacheKey = `${index}:${path}`;
-					const response = {
-						span: cache.get(cacheKey),
-						pathToCount: metadata.pathToCount,
-						overrides: metadata.overrides
-					};
-					res.writeHead(200, { "Content-Type": "application/json" });
-					res.end(JSON.stringify(response));
-				} catch (err) {
-					res.writeHead(400, { "Content-Type": "application/json" });
-					res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
-				}
-				return;
-			}
-			res.writeHead(404, { "Content-Type": "application/json" });
-			res.end(JSON.stringify({ error: "Not found" }));
-		})().catch((error) => {
-			if (!res.headersSent) {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ error: error instanceof Error ? error.message : "Internal server error" }));
-			}
-		});
-	});
-	const port = await findAvailablePort(startPort);
-	return new Promise((resolve, reject) => {
-		server.listen(port, () => {
-			resolve({
-				port,
-				server,
-				cache,
-				setMetadata: (newMetadata) => {
-					metadata = newMetadata;
-				}
-			});
-		});
-		server.on("error", reject);
-	});
-}
-//#endregion
-//#region src/sse-client.ts
-const HEARTBEAT_INTERVAL = 5e3;
-const MAX_MISSED_HEARTBEATS = 3;
-/**
-* SSE client for rollout debugging sessions
-* Connects to the Laminar backend and listens for run events
-*/
-var SSEClient = class extends events.EventEmitter {
-	constructor(options) {
-		super();
-		this.lastHeartbeat = Date.now();
-		this.isShutdown = false;
-		this.client = options.client;
-		this.sessionId = options.sessionId;
-		this.params = options.params;
-		this.name = options.name;
-	}
-	/**
-	* Connects to the SSE endpoint
-	*/
-	async connectAndListen() {
-		if (this.isShutdown) return;
-		this.abortController = new AbortController();
-		this.lastHeartbeat = Date.now();
-		try {
-			const response = await this.client.rolloutSessions.connect({
-				sessionId: this.sessionId,
-				params: this.params,
-				signal: this.abortController.signal,
-				name: this.name
-			});
-			this.emit("connected");
-			this.startHeartbeatCheck();
-			await this.parseSSEStream(response.body);
-		} catch (error) {
-			if (error.name === "AbortError") return;
-			this.emit("error", error);
-			if (!this.isShutdown) this.scheduleReconnect();
-		}
-	}
-	/**
-	* Parses SSE stream and emits events
-	*/
-	async parseSSEStream(body) {
-		const reader = body.getReader();
-		const decoder = new TextDecoder();
-		const parser = (0, eventsource_parser.createParser)({ onEvent: (event) => {
-			this.processSSEEvent(event);
-		} });
-		try {
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				const chunk = decoder.decode(value, { stream: true });
-				parser.feed(chunk);
-			}
-		} finally {
-			reader.releaseLock();
-		}
-		if (!this.isShutdown) this.scheduleReconnect();
-	}
-	/**
-	* Processes a parsed SSE event
-	*/
-	processSSEEvent(event) {
-		if (!event.data) return;
-		try {
-			if (event.event === "heartbeat") {
-				this.lastHeartbeat = Date.now();
-				this.emit("heartbeat");
-			} else if (event.event === "run") {
-				const runEvent = {
-					event_type: "run",
-					data: JSON.parse(event.data)
-				};
-				this.emit("run", runEvent);
-			} else if (event.event === "handshake") {
-				const handshakeEvent = {
-					event_type: "handshake",
-					data: JSON.parse(event.data)
-				};
-				this.emit("handshake", handshakeEvent);
-			} else if (event.event === "stop") this.emit("stop");
-		} catch (error) {
-			this.emit("error", /* @__PURE__ */ new Error(`Failed to parse SSE event data: ${error}`));
-		}
-	}
-	/**
-	* Starts checking for missed heartbeats
-	*/
-	startHeartbeatCheck() {
-		this.stopHeartbeatCheck();
-		this.heartbeatCheckTimer = setInterval(() => {
-			if (Date.now() - this.lastHeartbeat > HEARTBEAT_INTERVAL * MAX_MISSED_HEARTBEATS) {
-				this.emit("heartbeat_timeout");
-				this.reconnect();
-			}
-		}, HEARTBEAT_INTERVAL);
-	}
-	/**
-	* Stops heartbeat checking
-	*/
-	stopHeartbeatCheck() {
-		if (this.heartbeatCheckTimer) {
-			clearInterval(this.heartbeatCheckTimer);
-			this.heartbeatCheckTimer = void 0;
-		}
-	}
-	/**
-	* Schedules a reconnection attempt
-	*/
-	scheduleReconnect() {
-		if (this.reconnectTimer || this.isShutdown) return;
-		this.emit("reconnecting");
-		this.reconnectTimer = setTimeout(() => {
-			this.reconnectTimer = void 0;
-			this.reconnect();
-		}, 1e3);
-	}
-	/**
-	* Reconnects to the SSE endpoint
-	*/
-	reconnect() {
-		this.disconnect(true);
-		this.connectAndListen().catch((error) => {
-			this.emit("error", error);
-		});
-	}
-	/**
-	* Disconnects from the SSE endpoint
-	*/
-	disconnect(stopReconnect = true) {
-		if (this.abortController) {
-			this.abortController.abort();
-			this.abortController = void 0;
-		}
-		this.stopHeartbeatCheck();
-		if (stopReconnect && this.reconnectTimer) {
-			clearTimeout(this.reconnectTimer);
-			this.reconnectTimer = void 0;
-		}
-	}
-	/**
-	* Updates the function metadata (params, name) and reconnects
-	*/
-	updateMetadata(params, name) {
-		this.params = params;
-		this.name = name;
-		this.reconnect();
-	}
-	/**
-	* Shuts down the SSE client gracefully
-	*/
-	shutdown() {
-		this.isShutdown = true;
-		this.disconnect(true);
-		this.emit("shutdown");
-		this.removeAllListeners();
-	}
+const normalizeTraceId = (traceId) => {
+	const id = traceId.trim().toLowerCase().replace(/^0x/, "");
+	if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) return id;
+	if (/^[0-9a-f]{32}$/.test(id)) 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");
+	throw new Error(`Invalid trace id "${traceId}". Expected a UUID or a 32-char OTel hex trace id.`);
 };
 /**
-* Creates an SSE client (does not auto-connect)
-* Call client.connect() after registering event listeners
+* Extract the note from a trace's `metadata` column as returned by the SQL
+* endpoint (a JSON string; tolerate an already-parsed object too). Missing /
+* malformed metadata reads as "no note".
 */
-function createSSEClient(options) {
-	return new SSEClient(options);
-}
-//#endregion
-//#region src/subprocess/executor.ts
-const logger$3 = initializeLogger();
-/**
-* Track and kill the currently running subprocess
-*/
-var SubprocessManager = class {
-	constructor() {
-		this.currentProcess = null;
-	}
-	/**
-	* Execute a subprocess and track it
-	*/
-	async execute(options) {
-		const { command, args, config } = options;
-		const child = (0, child_process.spawn)(command, args, { stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		] });
-		this.currentProcess = child;
-		return new Promise((resolve, reject) => {
-			const result = void 0;
-			let hasError = false;
-			readline.createInterface({
-				input: child.stdout,
-				crlfDelay: Infinity
-			}).on("line", (line) => {
-				if (line.startsWith("__LMNR_WORKER__:")) try {
-					const messageJson = line.substring(16);
-					const message = JSON.parse(messageJson);
-					switch (message.type) {
-						case "log":
-							logger$3[message.level](message.message);
-							break;
-						case "error":
-							hasError = true;
-							logger$3.error(`Worker error: ${message.error}`);
-							if (message.stack) logger$3.error(message.stack);
-							break;
-					}
-				} catch {
-					logger$3.debug("Failed to parse worker protocol message. Printing raw line");
-					console.log(line.substring(16));
-				}
-				else console.log(line);
-			});
-			child.stderr.on("data", (data) => {
-				process.stderr.write(data);
-			});
-			child.on("exit", (code, signal) => {
-				if (this.currentProcess?.pid === child.pid) this.currentProcess = null;
-				if (signal) reject(/* @__PURE__ */ new Error(`Worker terminated by signal: ${signal}`));
-				else if (code === 0) resolve(result);
-				else {
-					if (!hasError) logger$3.error(`Worker exited with code ${code}`);
-					reject(/* @__PURE__ */ new Error(`Worker exited with code ${code}`));
-				}
-			});
-			child.on("error", (error) => {
-				this.currentProcess = null;
-				reject(/* @__PURE__ */ new Error(`Failed to spawn worker: ${error.message}`));
-			});
-			child.stdin?.write(JSON.stringify(config) + "\n");
-			child.stdin?.end();
-		});
-	}
-	/**
-	* Kill the currently running subprocess
-	* @returns true if a process was killed, false if no process was running
-	*/
-	kill() {
-		if (this.currentProcess) {
-			const processToKill = this.currentProcess;
-			this.currentProcess.kill("SIGTERM");
-			setTimeout(() => {
-				if (processToKill && processToKill.exitCode === null) {
-					logger$3.warn("Child process did not terminate, using SIGKILL");
-					processToKill.kill("SIGKILL");
-				}
-			}, 5e3);
-			return true;
-		}
-		return false;
-	}
-	/**
-	* Check if a subprocess is currently running
-	*/
-	isRunning() {
-		return this.currentProcess !== null;
-	}
-};
-//#endregion
-//#region src/worker-registry.ts
-/**
-* Default workers mapped by file extension
-*/
-const DEFAULT_WORKERS = {
-	".ts": {
-		command: "node",
-		args: []
-	},
-	".cts": {
-		command: "node",
-		args: []
-	},
-	".mts": {
-		command: "node",
-		args: []
-	},
-	".tsx": {
-		command: "node",
-		args: []
-	},
-	".jsx": {
-		command: "node",
-		args: []
-	},
-	".js": {
-		command: "node",
-		args: []
-	},
-	".mjs": {
-		command: "node",
-		args: []
-	},
-	".cjs": {
-		command: "node",
-		args: []
-	},
-	".py": {
-		command: "python3",
-		args: ["-m", "lmnr.cli.worker"]
-	}
-};
-/**
-* Get the worker command for a given file path or module.
-* Resolves the TypeScript worker dynamically from @lmnr-ai/lmnr package.
-*/
-function getWorkerCommand(filePath, options) {
-	if (options?.pythonModule) return {
-		command: "python3",
-		args: ["-m", "lmnr.cli.worker"]
-	};
-	if (!filePath) throw new Error("Either filePath or pythonModule must be provided");
-	const ext = path.extname(filePath);
-	if (!DEFAULT_WORKERS[ext]) throw new Error(`Unsupported file extension: ${ext}. Supported extensions: ${Object.keys(DEFAULT_WORKERS).join(", ")}`);
-	const worker = DEFAULT_WORKERS[ext];
-	if ([
-		".ts",
-		".tsx",
-		".js",
-		".mjs",
-		".cjs",
-		".mts",
-		".cts",
-		".jsx"
-	].includes(ext)) try {
-		const workerPath = require.resolve("@lmnr-ai/lmnr/dist/cli/worker/index.cjs");
-		return {
-			command: worker.command,
-			args: [workerPath]
-		};
-	} catch (error) {
-		throw new Error(`Failed to resolve TypeScript/JavaScript worker from @lmnr-ai/lmnr package. Make sure @lmnr-ai/lmnr is installed. Error: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	return worker;
-}
-//#endregion
-//#region src/commands/dev/metadata.ts
-const logger$2 = initializeLogger();
-const TS_JS_EXTENSIONS = [
-	".ts",
-	".tsx",
-	".js",
-	".mjs",
-	".cjs",
-	".jsx",
-	".mts",
-	".cts"
-];
-const EXTENSIONS_TO_DISCOVER_METADATA = [...TS_JS_EXTENSIONS, ".py"];
-/**
-* Protocol prefix for metadata discovery responses
-* This allows us to safely parse JSON even if there are other log statements in stdout
-*/
-const METADATA_PROTOCOL_PREFIX = "LMNR_METADATA:";
-const logLmnrPackageNotFoundAndExit = () => {
-	logger$2.error("@lmnr-ai/lmnr package not found or outdated. For JS/TS projects, please install the latest version of @lmnr-ai/lmnr in your project: npm install @lmnr-ai/lmnr\nYou might need to run `lmnr-cli` from the root of your project");
-	process.exit(1);
-};
-/**
-* Discovers function metadata for TypeScript and JavaScript files by:
-* 1. Extracting TypeScript metadata (params with types from source - TS only)
-* 2. Building and loading the module with esbuild
-* 3. Selecting the appropriate function
-* 4. Matching metadata by span name
-*
-* For JavaScript files, TypeScript metadata extraction fails gracefully, but runtime
-* parameter extraction via regex still works (param names without types).
-*/
-const discoverTypeScriptMetadata = async (filePath, options) => {
-	let extractRolloutFunctions;
-	let buildFile;
-	let loadModule;
-	let selectRolloutFunction;
-	try {
-		const lmnrPackage = "@lmnr-ai/lmnr";
-		const tsParserPath = require.resolve(`${lmnrPackage}/dist/cli/worker/ts-parser.cjs`);
-		const buildModulePath = require.resolve(`${lmnrPackage}/dist/cli/worker/build.cjs`);
-		delete require.cache[tsParserPath];
-		delete require.cache[buildModulePath];
-		extractRolloutFunctions = require(tsParserPath).extractRolloutFunctions;
-		const buildModule = require(buildModulePath);
-		buildFile = buildModule.buildFile;
-		loadModule = buildModule.loadModule;
-		selectRolloutFunction = buildModule.selectRolloutFunction;
-		if (!extractRolloutFunctions || !buildFile || !loadModule || !selectRolloutFunction) {
-			logger$2.error("Missing exports from @lmnr-ai/lmnr modules. This may indicate an outdated package version.");
-			logLmnrPackageNotFoundAndExit();
-		}
-	} catch (error) {
-		if (error.code === "MODULE_NOT_FOUND") logLmnrPackageNotFoundAndExit();
-		logger$2.error(`Unexpected error loading @lmnr-ai/lmnr modules: ${error.message}`);
-		throw error;
-	}
-	let paramsMetadata;
-	try {
-		paramsMetadata = extractRolloutFunctions(filePath);
-		logger$2.debug(`Extracted TypeScript metadata for ${paramsMetadata?.size} functions`);
-	} catch (error) {
-		logger$2.warn("Failed to extract TypeScript metadata, falling back to runtime parsing: " + (error instanceof Error ? error.message : String(error)));
-	}
-	const moduleText = await buildFile(filePath, {
-		externalPackages: options.externalPackages,
-		dynamicImportsToSkip: options.dynamicImportsToSkip
-	});
-	loadModule({
-		filename: filePath,
-		moduleText
-	});
-	const selectedFunction = selectRolloutFunction(options.function);
-	if (paramsMetadata) {
-		logger$2.debug(`Available TS metadata keys: ${Array.from(paramsMetadata.keys()).join(", ")}`);
-		logger$2.debug(`Looking for span name: ${selectedFunction.name} (runtime key: ${selectedFunction.exportName})`);
-		let foundMetadata = null;
-		for (const [exportName, metadata] of paramsMetadata.entries()) {
-			logger$2.debug(`Checking ${exportName}: span name = ${metadata.name}, export name = ${exportName}`);
-			if (metadata.name === selectedFunction.name) {
-				foundMetadata = metadata;
-				logger$2.debug(`Match. Export name: ${exportName}, span name: ${metadata.name}`);
-				break;
-			}
-		}
-		if (foundMetadata) {
-			selectedFunction.params = foundMetadata.params;
-			logger$2.debug(`Using TypeScript metadata for span: ${selectedFunction.name}`);
-		} else logger$2.info(`No TypeScript metadata found for span name: ${selectedFunction.name}`);
-	}
-	return {
-		functionName: selectedFunction.name,
-		params: selectedFunction.params || []
-	};
-};
-/**
-* Helper to execute subprocess commands
-*/
-const execCommand = async (command, args) => new Promise((resolve, reject) => {
-	const { spawn } = require("child_process");
-	const child = spawn(command, args);
-	let stdout = "";
-	let stderr = "";
-	child.stdout.on("data", (data) => {
-		stdout += data.toString();
-	});
-	child.stderr.on("data", (data) => {
-		stderr += data.toString();
-	});
-	child.on("close", (code) => {
-		if (code === 0) resolve({
-			stdout,
-			stderr
-		});
-		else reject(/* @__PURE__ */ new Error(`Command failed with code ${code}: ${stderr}`));
-	});
-	child.on("error", (error) => {
-		reject(error);
-	});
-});
-/**
-* Extracts JSON metadata from stdout that may contain other log statements
-* Looks for lines matching the protocol prefix and parses the JSON payload
-*
-* @param stdout - Raw stdout output that may contain logs and metadata
-* @returns Parsed JSON object
-* @throws Error if no valid metadata line is found or JSON parsing fails
-*/
-const extractMetadataFromStdout = (stdout) => {
-	const prefixPositions = [];
-	let searchStart = 0;
-	while (true) {
-		const pos = stdout.indexOf(METADATA_PROTOCOL_PREFIX, searchStart);
-		if (pos === -1) break;
-		prefixPositions.push(pos);
-		searchStart = pos + 14;
-	}
-	if (prefixPositions.length === 0) try {
-		return JSON.parse(stdout.trim());
-	} catch {
-		throw new Error("No metadata found in output. Please make sure you are running the latest version of `lmnr` python package.");
-	}
-	let lastValidJson = null;
-	for (const pos of prefixPositions) {
-		const startPos = pos + 14;
-		const jsonText = stdout.slice(startPos).trim();
-		const nextNewline = stdout.indexOf("\n", startPos);
-		if (nextNewline !== -1) {
-			const lineText = stdout.slice(startPos, nextNewline).trim();
-			try {
-				lastValidJson = JSON.parse(lineText);
-				continue;
-			} catch {}
-		}
+const readNoteFromMetadata = (metadata) => {
+	let parsed = metadata;
+	if (typeof metadata === "string") {
+		if (metadata === "") return "";
 		try {
-			let depth = 0;
-			let inString = false;
-			let escapeNext = false;
-			let firstChar = -1;
-			for (let i = 0; i < jsonText.length; i++) {
-				const char = jsonText[i];
-				if (escapeNext) {
-					escapeNext = false;
-					continue;
-				}
-				if (char === "\\" && inString) {
-					escapeNext = true;
-					continue;
-				}
-				if (char === "\"") {
-					inString = !inString;
-					continue;
-				}
-				if (inString) continue;
-				if (char === "{" || char === "[") {
-					if (firstChar === -1) firstChar = i;
-					depth++;
-				} else if (char === "}" || char === "]") {
-					depth--;
-					if (depth === 0 && firstChar !== -1) {
-						const candidate = jsonText.slice(0, i + 1);
-						lastValidJson = JSON.parse(candidate);
-						break;
-					}
-				}
-			}
-			if (depth !== 0 || firstChar === -1) lastValidJson = JSON.parse(jsonText);
+			parsed = JSON.parse(metadata);
 		} catch {
-			continue;
+			return "";
 		}
 	}
-	if (lastValidJson === null) throw new Error("No valid metadata JSON found in output. Please make sure you are running the latest version of `lmnr` python package.");
-	return lastValidJson;
-};
-/**
-* Discovers function metadata for Python files/modules by calling the lmnr Python CLI
-*/
-const discoverPythonMetadata = async (filePathOrModule, options) => {
-	logger$2.debug(`Discovering Python metadata for ${filePathOrModule}`);
-	const args = ["discover"];
-	if (options.pythonModule) args.push("--module", options.pythonModule);
-	else args.push("--file", filePathOrModule);
-	if (options.function) args.push("--function", options.function);
-	try {
-		const response = extractMetadataFromStdout((await execCommand("lmnr", args)).stdout);
-		return {
-			functionName: response.name,
-			params: response.params || []
-		};
-	} catch (error) {
-		const errorMessage = error instanceof Error ? error.message : String(error);
-		logger$2.error(`Error while loading Python file/module: ${errorMessage}`);
-		if (errorMessage.toLowerCase().includes("command not found") || errorMessage.includes("spawn lmnr ENOENT")) logger$2.info(`HINT: Make sure latest version of \`lmnr\` python package is installed. \`pip install --upgrade lmnr\`, or if you are running this command from a virtual environment, make sure to activate it. For \`uv\` users, rerun the command with \`uv run\`, e.g. "uv run npx lmnr-cli dev ${filePathOrModule}"`);
-		throw error;
-	}
-};
-/**
-* Generic metadata discovery dispatcher that routes to language-specific implementations
-*/
-const discoverFunctionMetadata = async (filePathOrModule, options) => {
-	if (options.pythonModule) return await discoverPythonMetadata(filePathOrModule, options);
-	const ext = path.extname(filePathOrModule);
-	if (TS_JS_EXTENSIONS.includes(ext)) return await discoverTypeScriptMetadata(filePathOrModule, options);
-	if (ext === ".py") return await discoverPythonMetadata(filePathOrModule, options);
-	logger$2.warn(`No metadata discovery available for ${ext} files`);
-	return {
-		functionName: options.function || path.basename(filePathOrModule, ext),
-		params: []
-	};
+	if (typeof parsed !== "object" || parsed === null) return "";
+	const note = parsed[NOTE_METADATA_KEY];
+	return typeof note === "string" ? note : "";
 };
 //#endregion
-//#region src/commands/dev/index.ts
-const logger$1 = initializeLogger();
-function newUUID() {
-	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
-	return (0, uuid.v4)();
-}
-function getFrontendUrl(baseUrl, frontendPort) {
-	let url = baseUrl ?? "https://api.lmnr.ai";
-	if (url === "https://api.lmnr.ai") url = "https://www.laminar.sh";
-	url = url.replace(/\/$/, "");
-	if (/localhost|127\.0\.0\.1/.test(url)) {
-		const port = frontendPort ?? url.match(/:\d{1,5}$/g)?.[0]?.slice(1) ?? 5667;
-		url = url.replace(/:\d{1,5}$/g, "");
-		return `${url}:${port}`;
-	}
-	return url;
-}
-/**
-* Parses request arguments, attempting JSON parse for strings
-*/
-const tryParseArg = (arg) => {
-	if (typeof arg === "string") try {
-		return JSON.parse(arg);
-	} catch {
-		return arg;
-	}
-	return arg;
-};
+//#region src/commands/debug/index.ts
+const logger$2 = initializeLogger();
 /**
-* Handles a run event from the backend
+* Upsert the display name of a debug session. Update-only on the backend: a
+* session id unknown to the project 404s rather than creating a ghost session.
 */
-const handleRunEvent = async (event, sessionId, filePathOrModule, client, cacheServerPort, cache, setMetadata, options, subprocessManager) => {
-	logger$1.debug("Received run event");
-	const { trace_id, path_to_count, args: rawArgs, overrides } = event.data;
-	const parsedArgs = Array.isArray(rawArgs) ? rawArgs.map(tryParseArg) : Object.fromEntries(Object.entries(rawArgs).map(([key, value]) => [key, tryParseArg(value)]));
-	cache.clear();
-	setMetadata({
-		pathToCount: {},
-		overrides
+const handleDebugSessionSetName = async (sessionId, name, options) => {
+	const client = new LaminarClient({
+		projectApiKey: options.projectApiKey,
+		baseUrl: options.baseUrl,
+		port: options.port
 	});
 	try {
-		if (!trace_id || trace_id.trim() === "") logger$1.info("No spans in cache, starting fresh");
-		else {
-			const paths = Object.keys(path_to_count || {});
-			if (paths.length === 0) logger$1.info("No spans to cache, starting fresh");
-			else {
-				const query = `
-          SELECT name, input, output, attributes, path
-          FROM spans
-          WHERE trace_id = {traceId:UUID}
-            AND path IN {paths:String[]}
-          ORDER BY start_time ASC
-        `;
-				logger$1.debug(`Querying spans from trace ${trace_id}...`);
-				const spans = await client.sql.query(query, {
-					traceId: trace_id,
-					paths
-				});
-				logger$1.debug(`Received ${spans.length} spans from backend`);
-				const spansByPath = {};
-				for (const span of spans) {
-					const path$2 = span.path;
-					if (!spansByPath[path$2]) spansByPath[path$2] = [];
-					spansByPath[path$2].push(span);
-				}
-				for (const [path$3, pathSpans] of Object.entries(spansByPath)) {
-					const maxCount = path_to_count?.[path$3] || 0;
-					const spansToCache = pathSpans.slice(0, maxCount);
-					spansToCache.forEach((span, index) => {
-						let parsedInput;
-						let parsedOutput;
-						let parsedAttributes;
-						try {
-							parsedInput = typeof span.input === "string" ? JSON.parse(span.input) : span.input;
-						} catch {
-							parsedInput = span.input;
-						}
-						try {
-							parsedOutput = typeof span.output === "string" ? span.output : JSON.stringify(span.output);
-						} catch {
-							parsedOutput = String(span.output);
-						}
-						try {
-							parsedAttributes = typeof span.attributes === "string" ? JSON.parse(span.attributes) : span.attributes;
-						} catch {
-							parsedAttributes = {};
-						}
-						const cachedSpan = {
-							name: span.name,
-							input: parsedInput,
-							output: parsedOutput,
-							attributes: parsedAttributes
-						};
-						const cacheKey = `${index}:${path$3}`;
-						cache.set(cacheKey, cachedSpan);
-					});
-					logger$1.info(`Cached ${spansToCache.length} spans for path: ${path$3}`);
-				}
-				setMetadata({
-					pathToCount: path_to_count || {},
-					overrides
-				});
-			}
-		}
-		const baseUrl = options.baseUrl ?? process.env.LMNR_BASE_URL ?? "https://api.lmnr.ai";
-		const httpPort = options.port ?? (baseUrl.match(/:\d{1,5}$/g) ? parseInt(baseUrl.match(/:\d{1,5}$/g)[0].slice(1)) : 443);
-		const grpcPort = options.grpcPort ?? 8443;
-		const env = {
-			LMNR_ROLLOUT_SESSION_ID: sessionId,
-			LMNR_ROLLOUT_STATE_SERVER_ADDRESS: `http://localhost:${cacheServerPort}`
-		};
-		const workerConfig = {
-			filePath: options.pythonModule ? void 0 : filePathOrModule,
-			modulePath: options.pythonModule,
-			functionName: options.function,
-			args: parsedArgs,
-			env,
-			cacheServerPort,
-			baseUrl,
-			projectApiKey: options.projectApiKey,
-			httpPort,
-			grpcPort,
-			externalPackages: options.externalPackages,
-			dynamicImportsToSkip: options.dynamicImportsToSkip
-		};
-		const workerCommand = options.command ? {
-			command: options.command,
-			args: options.commandArgs ?? []
-		} : getWorkerCommand(options.pythonModule ? void 0 : filePathOrModule, options);
-		try {
-			await client.rolloutSessions.setStatus({
-				sessionId,
-				status: "RUNNING"
-			});
-		} catch (error) {
-			logger$1.error(`Error setting debugger session status: ${error instanceof Error ? error.message : error}`);
-		}
-		await subprocessManager.execute({
-			command: workerCommand.command,
-			args: workerCommand.args,
-			config: workerConfig
+		await client.rolloutSessions.setName({
+			sessionId,
+			name
 		});
-		try {
-			await client.rolloutSessions.setStatus({
+		if (options.json) {
+			outputJson({
 				sessionId,
-				status: "FINISHED"
+				name
 			});
-		} catch (error) {
-			logger$1.error(`Error setting debugger session status: ${error instanceof Error ? error.message : error}`);
+			return;
 		}
+		logger$2.info(`Set name of session ${sessionId} to "${name}".`);
 	} catch (error) {
-		logger$1.error(`Error handling run event: ${error instanceof Error ? error.message : error}`);
-		if (error instanceof Error && error.stack) logger$1.error(error.stack);
-		try {
-			await client.rolloutSessions.setStatus({
-				sessionId,
-				status: "FINISHED"
-			});
-		} catch (error) {
-			logger$1.error(`Error setting debugger session status: ${error instanceof Error ? error.message : error}`);
-		}
+		if (options.json) outputJsonError(error);
+		logger$2.error(`Failed to set session name: ${errorMessage(error)}`);
+		process.exit(1);
 	}
 };
+const SUMMARY_PAGE_SIZE = 1e3;
 /**
-* Main dev command handler
+* Print a per-trace summary of a debug session: every trace whose metadata
+* groups it to the session (`rollout.session_id`), oldest first, with the
+* agent-authored note (`rollout.note`) attached to each.
 */
-async function runDev(filePath, options = {}) {
-	const isPythonModule = !!options.pythonModule;
-	const filePathOrModule = filePath || options.pythonModule;
-	let didLogHandshake = false;
-	const sessionId = newUUID();
+const handleDebugSessionSummary = async (sessionId, options) => {
 	const client = new LaminarClient({
-		baseUrl: options.baseUrl,
 		projectApiKey: options.projectApiKey,
+		baseUrl: options.baseUrl,
 		port: options.port
 	});
-	logger$1.debug("Starting cache server...");
-	const { port: cacheServerPort, server: cacheServer, cache, setMetadata } = await startCacheServer();
-	logger$1.debug(`Cache server started on port ${cacheServerPort}`);
-	const subprocessManager = new SubprocessManager();
-	let functionName = options.function;
-	let params = [];
 	try {
-		if (isPythonModule || filePath && EXTENSIONS_TO_DISCOVER_METADATA.includes(path.extname(filePath))) {
-			logger$1.debug("Discovering entrypoint functions...");
-			const metadata = await discoverFunctionMetadata(filePathOrModule, options);
-			functionName = metadata.functionName;
-			params = metadata.params;
-			logger$1.info(`Serving function: ${functionName}`);
-			logger$1.debug(`Function parameters: ${JSON.stringify(params, null, 2)}`);
-		} else if (filePath) {
-			functionName = options.function || path.basename(filePath, path.extname(filePath));
-			logger$1.warn(`Metadata discovery not available for ${path.extname(filePath)} files`);
+		const traces = [];
+		let offset = 0;
+		for (;;) {
+			const rows = await client.sql.query("SELECT id, formatDateTime(end_time, '%Y-%m-%dT%H:%i:%S.%fZ') AS end_time, metadata FROM traces WHERE simpleJSONExtractString(metadata, 'rollout.session_id') = {session_id:String} ORDER BY start_time LIMIT {limit:UInt32} OFFSET {offset:UInt32}", {
+				session_id: sessionId,
+				limit: SUMMARY_PAGE_SIZE,
+				offset
+			});
+			for (const row of rows) traces.push({
+				note: readNoteFromMetadata(row.metadata),
+				traceId: String(row.id ?? ""),
+				endTime: String(row.end_time ?? "")
+			});
+			if (rows.length < SUMMARY_PAGE_SIZE) break;
+			offset += SUMMARY_PAGE_SIZE;
 		}
-	} catch (error) {
-		logger$1.error("Failed to discover entrypoint functions: " + (error instanceof Error ? error.message : String(error)));
-		cacheServer.close();
-		throw error;
-	}
-	logger$1.debug("Setting up file watcher...");
-	const watcher = chokidar.default.watch(".", {
-		ignored: (path$4) => {
-			const ignoredDirs = [
-				"node_modules",
-				".git",
-				"dist",
-				"build",
-				".next",
-				"coverage",
-				".turbo",
-				"tmp",
-				"temp",
-				"venv",
-				".venv",
-				"virtualenv",
-				".virtualenv",
-				"__pycache__",
-				".pytest_cache",
-				".ruff_cache",
-				".mypy_cache",
-				".cache",
-				".DS_Store"
-			];
-			if (path$4.split(/[/\\]/).some((segment) => ignoredDirs.includes(segment))) return true;
-			if (path$4.endsWith(".log") || path$4.endsWith(".map")) return true;
-			return false;
-		},
-		persistent: true,
-		ignoreInitial: true,
-		awaitWriteFinish: {
-			stabilityThreshold: 100,
-			pollInterval: 100
+		if (options.json) {
+			outputJson(traces);
+			return;
 		}
-	});
-	logger$1.debug("Setting up SSE client...");
-	let sseClient = null;
-	try {
-		sseClient = createSSEClient({
-			client,
-			sessionId,
-			params,
-			name: functionName ?? ""
-		});
-		let currentRunPromise = null;
-		let stopRequested = false;
-		sseClient.on("heartbeat", () => {
-			logger$1.debug("Heartbeat received");
-		});
-		sseClient.on("run", (event) => {
-			if (currentRunPromise !== null) {
-				logger$1.warn("Already processing a run event, skipping new run");
-				return;
-			}
-			currentRunPromise = (async () => {
-				try {
-					stopRequested = false;
-					if (reloadScheduled) {
-						logger$1.info("Reloading function metadata before run...");
-						if (isPythonModule || filePath && EXTENSIONS_TO_DISCOVER_METADATA.includes(path.extname(filePath))) try {
-							const metadata = await discoverFunctionMetadata(filePathOrModule, options);
-							if (stopRequested) {
-								logger$1.info("Run cancelled during metadata discovery");
-								return;
-							}
-							logger$1.debug(`Updated function metadata: ${metadata.functionName}`);
-							logger$1.debug(`Updated parameters: ${JSON.stringify(metadata.params, null, 2)}`);
-							if (sseClient) {
-								sseClient.updateMetadata(metadata.params, metadata.functionName);
-								logger$1.debug("Notified backend of metadata changes");
-							}
-							reloadScheduled = false;
-						} catch (error) {
-							logger$1.error("Failed to update function metadata: " + (error instanceof Error ? error.message : String(error)));
-							if (error instanceof Error && error.stack) logger$1.debug(`Stack trace: ${error.stack}`);
-							return;
-						}
-						else reloadScheduled = false;
-					}
-					if (stopRequested) {
-						logger$1.info("Run cancelled before execution");
-						return;
-					}
-					await handleRunEvent(event, sessionId, filePathOrModule, client, cacheServerPort, cache, setMetadata, options, subprocessManager);
-				} catch (error) {
-					logger$1.error("Unhandled error in run event handler: " + (error instanceof Error ? error.message : String(error)));
-				} finally {
-					currentRunPromise = null;
-				}
-			})();
-		});
-		sseClient.on("handshake", (event) => {
-			const projectId = event.data.project_id;
-			const sessionId = event.data.session_id;
-			const frontendUrl = getFrontendUrl(options.baseUrl, options.frontendPort);
-			if (!didLogHandshake) logger$1.info(`View your session at ${frontendUrl}/project/${projectId}/debugger-sessions/${sessionId}`);
-			didLogHandshake = true;
-		});
-		sseClient.on("error", (error) => {
-			logger$1.warn(`Error connecting to backend: ${error.message}`);
-		});
-		sseClient.on("reconnecting", () => {
-			logger$1.info("Reconnecting to backend...");
-		});
-		sseClient.on("heartbeat_timeout", () => {
-			logger$1.debug("Heartbeat timeout, reconnecting...");
-		});
-		sseClient.on("stop", () => {
-			logger$1.debug("Stop event received");
-			stopRequested = true;
-			if (subprocessManager.kill()) logger$1.info("Current run cancelled");
-		});
-		let reloadTimeout = null;
-		let reloadScheduled = false;
-		watcher.on("change", (changedPath) => {
-			logger$1.info(`File changed: ${changedPath}, scheduling reload...`);
-			if (reloadTimeout) clearTimeout(reloadTimeout);
-			reloadTimeout = setTimeout(() => {
-				logger$1.debug("Marking reload as scheduled for next run...");
-				reloadTimeout = null;
-				reloadScheduled = true;
-			}, 100);
+		if (traces.length === 0) {
+			console.log(`No traces found for session ${sessionId}.`);
+			return;
+		}
+		const blocks = traces.map((trace) => {
+			const tag = `<trace id="${trace.traceId}" end-time="${trace.endTime}"/>`;
+			return trace.note ? `${trace.note}\n${tag}` : tag;
 		});
-		const shutdown = () => {
-			logger$1.debug("Shutting down...");
-			if (reloadTimeout) {
-				clearTimeout(reloadTimeout);
-				reloadTimeout = null;
-			}
-			reloadScheduled = false;
-			logger$1.debug("Closing file watcher...");
-			watcher.close().catch((error) => {
-				logger$1.error(`Failed to close file watcher: ${error instanceof Error ? error.message : error}`);
-			});
-			subprocessManager.kill();
-			logger$1.debug("Deleting debugger session...");
-			client.rolloutSessions.delete({ sessionId }).then(() => {
-				if (sseClient) sseClient.shutdown();
-				cacheServer.close(() => {
-					logger$1.debug("Cache server closed");
-				});
-				process.exit(0);
-			}).catch((error) => {
-				logger$1.warn(`Failed to delete debugger session: ${error instanceof Error ? error.message : error}`);
-				process.exit(1);
-			});
-		};
-		process.on("SIGINT", shutdown);
-		process.on("SIGTERM", shutdown);
-		process.stdin.resume();
-		logger$1.debug("Connecting to backend...");
-		await sseClient.connectAndListen();
+		console.log(blocks.join("\n\n"));
 	} catch (error) {
-		logger$1.error("Failed to start dev command: " + (error instanceof Error ? error.message : String(error)));
-		try {
-			await client.rolloutSessions.delete({ sessionId });
-		} catch {}
-		await watcher.close();
-		cacheServer.close(() => {
-			process.exit(1);
-		});
+		if (options.json) outputJsonError(error);
+		logger$2.error(`Failed to summarize session: ${errorMessage(error)}`);
+		process.exit(1);
 	}
-}
+};
 //#endregion
 //#region src/commands/sql/index.ts
-const logger = initializeLogger();
+const logger$1 = initializeLogger();
 const handleSqlQuery = async (query, options) => {
 	const client = new LaminarClient({
 		projectApiKey: options.projectApiKey,
@@ -2540,7 +1636,7 @@ const handleSqlQuery = async (query, options) => {
 		console.log(`\n${rows.length} row(s)\n`);
 	} catch (error) {
 		if (options.json) outputJsonError(error);
-		logger.error(`Query failed: ${error instanceof Error ? error.message : String(error)}`);
+		logger$1.error(`Query failed: ${errorMessage(error)}`);
 		process.exit(1);
 	}
 };
@@ -2591,27 +1687,59 @@ Available tables:
     data (String), target (String), metadata (String)
 `;
 //#endregion
+//#region src/commands/trace/index.ts
+const logger = initializeLogger();
+const NOTE_SEPARATOR = "\n\n";
+/**
+* Append a free-text note to an existing trace. Stored under the
+* `rollout.note` trace-metadata key via the post-factum metadata patch
+* endpoint. The patch endpoint is last-write-wins per key, so the current
+* note is read back first (via the SQL endpoint) and the new text is pushed
+* as `existing + "\n\n" + note`. The note may contain markdown /
+* span-reference links.
+*
+* The read-modify-write is not transactional: the patch lands via the async
+* ingestion queue, so a second append issued within ~a second of the first
+* can read the pre-patch note and drop the first append. Fine for the
+* intended cadence (one note per investigation step), not for concurrent
+* writers.
+*
+* TODO: revisit — make the append atomic server-side (e.g. an append mode on
+* the metadata patch endpoint that concatenates within the Postgres UPDATE,
+* which already serializes on the trace row lock).
+*/
+const handleTraceAppendNote = async (traceId, note, options) => {
+	const client = new LaminarClient({
+		projectApiKey: options.projectApiKey,
+		baseUrl: options.baseUrl,
+		port: options.port
+	});
+	try {
+		const id = normalizeTraceId(traceId);
+		const rows = await client.sql.query("SELECT metadata FROM traces WHERE id = {trace_id:UUID} LIMIT 1", { trace_id: id });
+		if (rows.length === 0) throw new Error(`Trace ${id} not found. If the run just finished, the trace may not be flushed yet. Retry in a few seconds.`);
+		const existing = readNoteFromMetadata(rows[0].metadata);
+		const updated = existing ? `${existing}${NOTE_SEPARATOR}${note}` : note;
+		await client.traces.pushMetadata(id, { [NOTE_METADATA_KEY]: updated }, { failOnNotFound: true });
+		if (options.json) {
+			outputJson({
+				traceId: id,
+				note: updated
+			});
+			return;
+		}
+		logger.info(`Appended note to trace ${id}.`);
+	} catch (error) {
+		if (options.json) outputJsonError(error);
+		logger.error(`Failed to append trace note: ${errorMessage(error)}`);
+		process.exit(1);
+	}
+};
+//#endregion
 //#region src/index.ts
 async function main() {
 	const program = new commander.Command();
 	program.name("lmnr-cli").description("CLI for the Laminar agent observability platform").version(version$1, "-v, --version", "display version number");
-	program.command("dev").description("Start a debugging session").argument("[file]", "Path to file containing the entrypoint function(s). Either `file` or `-m` must be provided.").option("-m, --python-module <module>", "Python module path (e.g., src.myfile). Either `file` or `-m` must be provided.").option("--function <name>", "Specific function to serve (if multiple entrypoint functions found)").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--grpc-port <port>", "Port for the Laminar gRPC backend. Defaults to 8443", (val) => parseInt(val, 10)).option("--frontend-port <port>", "Port for the Laminar frontend. Defaults to 5667", (val) => parseInt(val, 10)).option("--external-packages <packages...>", "[ADVANCED] List of packages to pass as external to esbuild. This will not link the packages directly into the dev file, but will instead require them at runtime. Read more: https://esbuild.github.io/api/#external").option("--dynamic-imports-to-skip <modules...>", "[ADVANCED] List of module names to skip when encountered as dynamic imports. These dynamic imports will resolve to an empty module to prevent build failures. This is meant to skip the imports that are not used in the entrypoint function itself.").option("--command <command>", "[ADVANCED] Custom command to run the worker (e.g., python3, node)").option("--command-args <args...>", "[ADVANCED] Arguments for the custom command").action(async (file, options) => {
-		if (!file && !options.pythonModule) {
-			console.error("Error: Must provide either a file path or --python-module (-m) flag");
-			process.exit(1);
-		}
-		if (file && options.pythonModule) {
-			console.error("Error: Cannot specify both file path and --python-module (-m) flag");
-			process.exit(1);
-		}
-		await runDev(file, options);
-	}).addHelpText("after", `
-Examples:
-  $ lmnr-cli dev agent.ts                    # TypeScript file
-  $ lmnr-cli dev agent.py                    # Python file (script mode)
-  $ lmnr-cli dev -m src.agent                # Python module (module mode)
-  $ lmnr-cli dev agent.ts --function myAgent # Specific function
-`);
 	const datasetsCmd = program.command("dataset").description("Manage datasets").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout");
 	datasetsCmd.command("list").description("List all datasets").action(async (_options, cmd) => {
 		await handleDatasetsList(cmd.optsWithGlobals());
@@ -2637,6 +1765,41 @@ Examples:
 	sqlCmd.command("schema").description("Show available tables and their columns").action(() => {
 		process.stdout.write(SQL_SCHEMA_HELP);
 	});
+	program.command("trace").description("Operate on existing traces").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").command("append-note").description("Append a free-text note to a trace (stored in trace metadata)").argument("<trace-id>", "Trace ID (UUID or 32-char OTel hex trace id)").argument("<note>", "Note text (may contain markdown)").action(async (traceId, note, _options, cmd) => {
+		await handleTraceAppendNote(traceId, note, cmd.optsWithGlobals());
+	}).addHelpText("after", `
+Notes accumulate: each call appends a new paragraph to the trace's existing
+note rather than overwriting it.
+
+Examples:
+  $ lmnr-cli trace append-note <trace-id> "Reproduced the timeout on the search tool."
+`);
+	const debugSessionCmd = program.command("debug").description("Operate on debug sessions").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").addHelpText("after", `
+Learn more about debugging features at https://laminar.sh/docs/platform/debugger
+`).command("session").description("Manage debug sessions").addHelpText("after", `
+Learn more about debugging features at https://laminar.sh/docs/platform/debugger
+`);
+	debugSessionCmd.command("set-name").description("Set the display name of a debug session").argument("<session-id>", "Debug session ID").argument("<name>", "Session display name").action(async (sessionId, name, _options, cmd) => {
+		await handleDebugSessionSetName(sessionId, name, cmd.optsWithGlobals());
+	}).addHelpText("after", `
+Examples:
+  $ lmnr-cli debug session set-name <session-id> "Fix report length + search tool"
+`);
+	debugSessionCmd.command("summary").description("Print every trace in a debug session with its note, oldest first").argument("<session-id>", "Debug session ID").action(async (sessionId, _options, cmd) => {
+		await handleDebugSessionSummary(sessionId, cmd.optsWithGlobals());
+	}).addHelpText("after", `
+Output is one block per trace (oldest first), the trace's note followed by a
+self-closing tag carrying the trace id and end time:
+
+  {note}
+  <trace id="{trace-id}" end-time="{end-time}"/>
+
+With --json, prints an array of {"note", "traceId", "endTime"} objects.
+
+Examples:
+  $ lmnr-cli debug session summary <session-id>
+  $ lmnr-cli debug session summary <session-id> --json
+`);
 	program.addHelpText("after", `
 Authentication:
   Most commands require a project API key. Provide it in one of two ways:
@@ -2645,15 +1808,15 @@ Authentication:
   Get your key at https://www.laminar.sh (Settings > Project API Keys).
 
 Examples:
-  lmnr-cli dev agent.ts                                    # Debugger TypeScript entrypoint
-  lmnr-cli dev agent.py                                    # Debugger Python script mode
-  lmnr-cli dev -m src.agent                                # Debugger Python module mode
   lmnr-cli dataset list --json                             # List all datasets
   lmnr-cli dataset push data.jsonl -n my-dataset --json    # Push data to a dataset
   lmnr-cli dataset pull output.jsonl -n my-dataset --json  # Pull data from a dataset
   lmnr-cli sql query "SELECT * FROM spans LIMIT 10" --json # Query spans
   lmnr-cli sql query "SELECT t.id, s.name FROM traces t JOIN spans s ON t.id = s.trace_id" --json
   lmnr-cli sql schema                                      # Show available tables
+  lmnr-cli trace append-note <trace-id> "note text"        # Append a note to a trace
+  lmnr-cli debug session set-name <session-id> "title"     # Rename a debug session
+  lmnr-cli debug session summary <session-id>              # Notes for each trace in a session
 
 For more information about the Laminar platfrom:
   Documentation: https://laminar.sh/docs
@@ -2662,7 +1825,7 @@ For more information about the Laminar platfrom:
 	await program.parseAsync();
 }
 main().catch((err) => {
-	console.error(err instanceof Error ? err.message : err);
+	console.error(errorMessage(err));
 	process.exit(1);
 });
 //#endregion