@hue-run/sdk 0.21.0 → 0.22.0

package/dist/cli/import-formats/zipkin.js

@@ -0,0 +1,219 @@
+import { ConversionError, isObject, } from "../traces-import-convert.js";
+import { otelTraceKey, OtelSpanCollector, unsigned } from "./otel-spans.js";
+import { readRecords } from "./rows.js";
+const object = (value) => isObject(value) ? value : undefined;
+const text = (value) => typeof value === "string" && value ? value : undefined;
+const KINDS = { SERVER: 2, CLIENT: 3, PRODUCER: 4, CONSUMER: 5 };
+/** A record with a Zipkin v2 span's hex trace and span ids and none of the fields other formats
+ * name a span with (`type`, `startTime`, `spanId`, `traceID`, `span_id`). */
+function hasSpanIds(value) {
+    if (!isObject(value))
+        return false;
+    const { traceId, id } = value;
+    if (typeof traceId !== "string" || typeof id !== "string")
+        return false;
+    if (!/^[0-9a-f]{16}(?:[0-9a-f]{16})?$/i.test(traceId) || !/^[0-9a-f]{16}$/i.test(id))
+        return false;
+    return !["type", "startTime", "spanId", "traceID", "span_id"].some((key) => key in value);
+}
+/** A Zipkin v2 span on its own: its ids and a field only a span records. */
+const isSpan = (value) => hasSpanIds(value) &&
+    (typeof value.timestamp === "number" ||
+        typeof value.duration === "number" ||
+        isObject(value.localEndpoint) ||
+        (typeof value.kind === "string" && value.kind in KINDS) ||
+        Array.isArray(value.annotations) ||
+        isObject(value.tags));
+/** Tags that describe the process, which the Collector keeps on the resource. */
+const RESOURCE_PREFIXES = [
+    "service.",
+    "telemetry.",
+    "deployment.",
+    "host.",
+    "os.",
+    "process.",
+    "container.",
+    "k8s.",
+    "cloud.",
+    "faas.",
+    "device.",
+];
+const attribute = (key, value) => ({
+    key,
+    value: typeof value === "number" ? { intValue: String(value) } : { stringValue: value },
+});
+/** An endpoint's address and port under `prefix` (`net.host`, `net.peer`). */
+function endpointAttributes(endpoint, prefix) {
+    if (!endpoint)
+        return [];
+    const address = text(endpoint.ipv4) ?? text(endpoint.ipv6);
+    const port = endpoint.port;
+    return [
+        ...(address ? [attribute(`${prefix}.ip`, address)] : []),
+        ...(typeof port === "number" && Number.isSafeInteger(port) && port > 0
+            ? [attribute(`${prefix}.port`, port)]
+            : []),
+    ];
+}
+function micros(value, what) {
+    if (value === undefined || value === null)
+        return undefined;
+    const count = unsigned(value);
+    if (count === undefined)
+        throw new ConversionError(`${what} is not a count of microseconds`);
+    return count * 1000n;
+}
+function readSpan(span, sequence) {
+    const { traceId, id } = span;
+    if (!hasSpanIds(span) || typeof traceId !== "string" || typeof id !== "string")
+        throw new ConversionError("a record that is not a Zipkin span");
+    const tagsValue = span.tags ?? {};
+    const tags = object(tagsValue);
+    if (!tags)
+        throw new ConversionError("tags is not an object");
+    const remaining = new Map();
+    for (const [key, value] of Object.entries(tags)) {
+        if (typeof value !== "string")
+            throw new ConversionError(`tag ${key} is not text`);
+        remaining.set(key, value);
+    }
+    const take = (key) => {
+        const value = remaining.get(key);
+        remaining.delete(key);
+        return value;
+    };
+    let kind = typeof span.kind === "string" ? (KINDS[span.kind] ?? 0) : 0;
+    const kindTag = take("span.kind");
+    if (!kind && kindTag === "internal")
+        kind = 1;
+    let status;
+    const code = take("otel.status_code");
+    const description = take("otel.status_description");
+    if (code !== undefined)
+        status = {
+            code: code === "OK" ? 1 : code === "ERROR" ? 2 : 0,
+            ...(description ? { message: description } : {}),
+        };
+    const error = take("error");
+    if (error !== undefined) {
+        const message = error && error !== "true" ? error : status?.message;
+        status = { code: 2, ...(message ? { message } : {}) };
+    }
+    const scopeName = take("otel.scope.name") ?? take("otel.library.name");
+    const scopeVersion = take("otel.scope.version") ?? take("otel.library.version");
+    const traceState = take("w3c.tracestate");
+    const local = object(span.localEndpoint);
+    const remote = object(span.remoteEndpoint);
+    const resource = [];
+    const service = text(local?.serviceName);
+    if (service)
+        resource.push(attribute("service.name", service));
+    const attributes = [];
+    for (const [key, value] of remaining)
+        (RESOURCE_PREFIXES.some((prefix) => key.startsWith(prefix)) ? resource : attributes).push(attribute(key, value));
+    attributes.push(...endpointAttributes(local, "net.host"));
+    attributes.push(...endpointAttributes(remote, "net.peer"));
+    const peer = text(remote?.serviceName);
+    if (peer)
+        attributes.push(attribute("peer.service", peer));
+    const annotations = span.annotations ?? [];
+    if (!Array.isArray(annotations))
+        throw new ConversionError("annotations is not a list");
+    const start = micros(span.timestamp, "timestamp");
+    if (start === 0n)
+        throw new ConversionError("timestamp is zero");
+    const duration = micros(span.duration, "duration");
+    const parentId = text(span.parentId);
+    if (parentId !== undefined && !/^[0-9a-f]{1,16}$/i.test(parentId))
+        throw new ConversionError("parentId is not a span id");
+    return {
+        traceId,
+        spanKey: id.toLowerCase(),
+        ...(parentId ? { parentKey: parentId.toLowerCase() } : {}),
+        name: text(span.name) ?? "",
+        kind,
+        ...(traceState ? { traceState } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(start !== undefined && duration !== undefined ? { end: start + duration } : {}),
+        attributes,
+        events: annotations.map((item) => {
+            const annotation = object(item);
+            if (!annotation || typeof annotation.value !== "string")
+                throw new ConversionError("an annotation without a value");
+            const time = micros(annotation.timestamp, "an annotation timestamp");
+            return { name: annotation.value, ...(time ? { time } : {}), attributes: [] };
+        }),
+        links: [],
+        ...(status ? { status } : {}),
+        resource,
+        ...(scopeName
+            ? { scope: { name: scopeName, ...(scopeVersion ? { version: scopeVersion } : {}) } }
+            : {}),
+        record: span,
+        sequence,
+    };
+}
+const serviceOf = (span) => {
+    const local = object(object(span.record)?.localEndpoint);
+    return text(local?.serviceName) ?? "";
+};
+const isShared = (span) => object(span.record)?.shared === true;
+/** Nests each server span that shares its id with its client under the client, and the server's
+ * children under the server when they ran on the same service, as Zipkin's UI builds its tree. */
+function nestShared(spans) {
+    const unshared = new Set(spans.filter((span) => !isShared(span)).map((span) => span.spanKey));
+    const sharedCount = new Map();
+    for (const span of spans)
+        if (isShared(span))
+            sharedCount.set(span.spanKey, (sharedCount.get(span.spanKey) ?? 0) + 1);
+    // A shared span is renamed when another span holds its id: its client, or another server.
+    const renamed = new Map();
+    const keyed = spans.map((span) => {
+        if (!isShared(span) || (!unshared.has(span.spanKey) && sharedCount.get(span.spanKey) === 1))
+            return span;
+        const spanKey = `${span.spanKey}#shared:${serviceOf(span)}`;
+        renamed.set(`${span.spanKey}\u0000${serviceOf(span)}`, spanKey);
+        return {
+            ...span,
+            spanKey,
+            sourceSpanId: span.spanKey,
+            ...(unshared.has(span.spanKey)
+                ? { parentKey: span.spanKey }
+                : span.parentKey !== undefined
+                    ? { parentKey: span.parentKey }
+                    : {}),
+        };
+    });
+    return keyed.map((span) => {
+        if (span.parentKey === undefined || span.sourceSpanId !== undefined)
+            return span;
+        const server = renamed.get(`${span.parentKey}\u0000${serviceOf(span)}`);
+        return server ? { ...span, parentKey: server } : span;
+    });
+}
+/** The spans a value holds: one span, or a list of spans. */
+const spansOf = (value) => isSpan(value)
+    ? [value]
+    : Array.isArray(value) && value.length && value.every(isObject) && value.some(isSpan)
+        ? value
+        : undefined;
+export const zipkin = {
+    id: "zipkin",
+    manifestFormat: "otlp_json",
+    detect: (value) => spansOf(value) !== undefined,
+    convert(value, context) {
+        const collector = context.collector(() => new OtelSpanCollector("zipkin", nestShared));
+        const records = spansOf(value) ?? [];
+        // A span's position in its source orders a trace that records no instant at all.
+        const base = context.source.line ?? context.source.index ?? 0;
+        readRecords(context, records.map((record, index) => ({ record, sequence: base + index })), ({ record }) => {
+            const traceId = object(record)?.traceId;
+            return typeof traceId === "string" && traceId ? otelTraceKey(traceId) : undefined;
+        }, ({ record, sequence }) => {
+            const span = object(record);
+            if (!span)
+                throw new ConversionError("a span that is not an object");
+            collector.add(readSpan(span, sequence), context.source.digest);
+        });
+    },
+};

package/dist/cli/import.d.ts

@@ -26,7 +26,7 @@ export interface ImportCommandIo {
      * in flight do not hold it until their requests time out. */
     exit?: (code: number) => void;
 }
-export declare const IMPORT_USAGE = "Usage: hue import langfuse [options]\n\nCopy traces from a Langfuse project into Hue. The import runs on this machine with your own\nLangfuse keys, which are sent only to Langfuse. Each observation becomes a span with the\nlangfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an\nimport without duplicating what was already sent. Langfuse's environment is also sent, as\nrecorded, as hue.import.source_environment; only traces Langfuse recorded in production add to\na user's World.\n\nLangfuse (keys from the environment or --env-path; the secret key never from the command line):\n  LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys\n  LANGFUSE_BASE_URL or LANGFUSE_HOST        Langfuse host (default https://cloud.langfuse.com)\n  --langfuse-host URL                       Langfuse host, instead of the variables\n  --langfuse-public-key KEY                 Public key, instead of LANGFUSE_PUBLIC_KEY\n\nHue:\n  HUE_API_KEY            The Hue project key the traces are sent with (environment, --env-path\n                         or ./.env.hue); not needed with --dry-run\n  --origin URL           Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --service-name NAME    service.name of the imported spans (default langfuse)\n\nSelection (newest first):\n  --from TIME            Traces that started at or after TIME: an ISO 8601 date (midnight UTC)\n                         or a date and time with a zone, such as 2026-01-01T09:00:00Z\n  --to TIME              Traces that started before TIME (default: an hour before the command\n                         starts, so traces still running are left for a later run)\n  --limit N              At most N traces\n  --trace-id ID          This Langfuse trace (repeatable); not with --from, --to or --limit\n\nContent:\n  --media                Download the files Langfuse media references (@@@langfuseMedia:\u2026@@@)\n                         point to and upload them to Hue; without it, references stay as text\n  --no-content           Send metadata only: no inputs, outputs, status messages or model\n                         parameters (content is sent by default, as the SDK records it)\n\nRun:\n  --dry-run              Read Langfuse and count what would be imported; send nothing to Hue\n  --yes                  Import without asking for confirmation (required without a terminal)\n  --env-path PATH        Load a dotenv file first (--env-file also works when it exists);\n                         ./.env.hue loads when HUE_API_KEY is not set. Variables already set win\n  -h, --help             Show this help\n\nExit codes: 0 every trace was imported, 1 a trace, span or file was not, 2 usage error,\n130 stopped (run the same command again to resume).";
+export declare const IMPORT_USAGE = "Usage: hue import langfuse [options]\n\nCopy traces from a Langfuse project into Hue. The import runs on this machine with your own\nLangfuse keys, which are sent only to Langfuse. Each observation becomes a span with the\nlangfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an\nimport without duplicating what was already sent. Langfuse's environment is also sent, as\nrecorded, as hue.import.source_environment. Ended traces with a resolved user can contribute to\nthat user's World regardless of deployment environment. Traces linked to Hue runs, World instances,\nor run executions never contribute. Hue's evaluation and simulation evidence and deliberately\nexcluded traces also stay excluded.\n\nLangfuse (keys from the environment or --env-path; the secret key never from the command line):\n  LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys\n  LANGFUSE_BASE_URL or LANGFUSE_HOST        Langfuse host (default https://cloud.langfuse.com)\n  --langfuse-host URL                       Langfuse host, instead of the variables\n  --langfuse-public-key KEY                 Public key, instead of LANGFUSE_PUBLIC_KEY\n\nHue:\n  HUE_API_KEY            The Hue project key the traces are sent with (environment, --env-path\n                         or ./.env.hue); not needed with --dry-run\n  --origin URL           Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --service-name NAME    service.name of the imported spans (default langfuse)\n\nSelection (newest first):\n  --from TIME            Traces that started at or after TIME: an ISO 8601 date (midnight UTC)\n                         or a date and time with a zone, such as 2026-01-01T09:00:00Z\n  --to TIME              Traces that started before TIME (default: an hour before the command\n                         starts, so traces still running are left for a later run)\n  --limit N              At most N traces\n  --trace-id ID          This Langfuse trace (repeatable); not with --from, --to or --limit\n\nContent:\n  --media                Download the files Langfuse media references (@@@langfuseMedia:\u2026@@@)\n                         point to and upload them to Hue; without it, references stay as text\n  --no-content           Send metadata only: no inputs, outputs, status messages or model\n                         parameters (content is sent by default, as the SDK records it)\n\nRun:\n  --dry-run              Read Langfuse and count what would be imported; send nothing to Hue\n  --yes                  Import without asking for confirmation (required without a terminal)\n  --env-path PATH        Load a dotenv file first (--env-file also works when it exists);\n                         ./.env.hue loads when HUE_API_KEY is not set. Variables already set win\n  -h, --help             Show this help\n\nExit codes: 0 every trace was imported, 1 a trace, span or file was not, 2 usage error,\n130 stopped (run the same command again to resume).";
 /** An instant of the window: an ISO 8601 date (midnight UTC) or a date and time with a zone. */
 export declare function parseInstant(option: string, value: string): string;
 /** The Langfuse host as a base URL without a trailing slash, or why it is refused. */

package/dist/cli/import.js

@@ -45,8 +45,10 @@ Copy traces from a Langfuse project into Hue. The import runs on this machine wi
 Langfuse keys, which are sent only to Langfuse. Each observation becomes a span with the
 langfuse.* attributes Hue reads; ids are kept, so running the same command again resumes an
 import without duplicating what was already sent. Langfuse's environment is also sent, as
-recorded, as hue.import.source_environment; only traces Langfuse recorded in production add to
-a user's World.
+recorded, as hue.import.source_environment. Ended traces with a resolved user can contribute to
+that user's World regardless of deployment environment. Traces linked to Hue runs, World instances,
+or run executions never contribute. Hue's evaluation and simulation evidence and deliberately
+excluded traces also stay excluded.
 
 Langfuse (keys from the environment or --env-path; the secret key never from the command line):
   LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY  The Langfuse project's API keys

package/dist/cli/mcp.d.ts

@@ -31,7 +31,7 @@ export declare const MCP_TOOLSETS: readonly ["all", "observe", "author", "evalua
 export declare const TOOLSETS_HEADER = "X-Hue-MCP-Toolsets";
 /** The header form of `?project=`, used by the sign-in Codex TOML to keep its URL bare. */
 export declare const PROJECT_HEADER = "X-Hue-MCP-Project";
-export declare const MCP_USAGE = "Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>\n                       [--auth key|oauth] [--read-only] [--project ID-OR-SLUG]\n                       [--toolsets NAMES] [--url URL]\n                       [--scope project|user] [--dry-run] [--print]\n\nConfigure a coding agent to use the Hue MCP server. A sign-in configuration holds only the\nURL: the client opens Hue in a browser, where you approve access to the projects of one\norganization. A key configuration references the HUE_MCP_KEY environment variable; a key value\nis never written.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --auth MODE     oauth: URL only, sign in with Hue in the client (claude-code, codex and\n                  conductor; their default)\n                  key: reference HUE_MCP_KEY (the default for the other clients and with\n                  --read-only). Without --auth, claude-code and codex keep the choice of\n                  an existing entry, and use a key for a new one when HUE_MCP_KEY is set\n  --read-only     Add ?read_only=true to a key configuration's URL so write tools are\n                  hidden; selects a key without --auth. A sign-in connection has Read and\n                  write access; use a Read key for read-only\n  --project VALUE Pin the connection to one project by id or slug. Its tools omit project_id,\n                  and the server is named hue-<value> so it can coexist with an unpinned hue\n  --toolsets NAMES\n                  Tools to list, comma-separated: all; the observe, author or evaluate\n                  profiles; or project, traces, eval_sets, runs, judges, cases, runners,\n                  environments, intents or docs. Added to the URL as ?toolsets=.\n                  Defaults: all for claude-code, codex and conductor,\n                  which search their own tools; observe for cursor. Without a selection\n                  Hue lists the production reads and search_hue_tools, which reaches\n                  every other tool\n  --url URL       Hue MCP endpoint (default https://mcp.hue.run/mcp)\n  --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs\n                  `claude mcp add --scope user`\n  --dry-run       Print the resulting file content or commands without writing or running\n  --print         Print the configuration snippet only\n  -h, --help      Show this help\n\nFiles: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the\ncurrent directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the\nsnippet for its user configuration file. conductor registers the server for its Claude Code\n(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.\ncodex mcp add signs in at once and waits up to 5 minutes for the browser, so without --auth\nand outside a terminal the command prints it instead of running it.";
+export declare const MCP_USAGE = "Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>\n                       [--auth key|oauth] [--read-only] [--project ID-OR-SLUG]\n                       [--toolsets NAMES] [--url URL]\n                       [--scope project|user] [--dry-run] [--print]\n\nConfigure a coding agent to use the Hue MCP server. A sign-in configuration holds only the\nURL: the client opens Hue in a browser, where you approve access to the projects of one\norganization. A key configuration references the HUE_MCP_KEY environment variable; a key value\nis never written.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --auth MODE     oauth: URL only, sign in with Hue in the client (claude-code, codex,\n                  conductor and cursor; their default)\n                  key: reference HUE_MCP_KEY (the default for the other clients and with\n                  --read-only). Without --auth, claude-code, codex and cursor keep the\n                  choice of an existing entry, and use a key for a new one when\n                  HUE_MCP_KEY is set\n  --read-only     Add ?read_only=true to a key configuration's URL so write tools are\n                  hidden; selects a key without --auth. A sign-in connection has Read and\n                  write access; use a Read key for read-only\n  --project VALUE Pin the connection to one project by id or slug. Its tools omit project_id,\n                  and the server is named hue-<value> so it can coexist with an unpinned hue\n  --toolsets NAMES\n                  Tools to list, comma-separated: all; the observe, author or evaluate\n                  profiles; or project, traces, eval_sets, runs, judges, cases, runners,\n                  environments, intents or docs. Added to the URL as ?toolsets=.\n                  Defaults: all for claude-code, codex and conductor,\n                  which search their own tools; observe for cursor. Without a selection\n                  Hue lists the production reads and search_hue_tools, which reaches\n                  every other tool\n  --url URL       Hue MCP endpoint (default https://mcp.hue.run/mcp)\n  --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs\n                  `claude mcp add --scope user`\n  --dry-run       Print the resulting file content or commands without writing or running\n  --print         Print the configuration snippet only\n  -h, --help      Show this help\n\nFiles: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the\ncurrent directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the\nsnippet for its user configuration file. conductor registers the server for its Claude Code\n(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.\ncodex mcp add signs in at once and waits up to 5 minutes for the browser, so without --auth\nand outside a terminal the command prints it instead of running it.";
 /**
  * A URL as a POSIX shell word for printed commands: `?` is a zsh glob and `&` ends a command, so a
  * URL with a query (such as `?read_only=true`) is single-quoted. Executed commands pass argv.
@@ -103,6 +103,10 @@ export declare function renderMcpSignInSnippets(url: string, serverName?: string
         url: string;
     };
     claudeCodeProjectJson: string;
+    cursorServer: {
+        url: string;
+    };
+    cursorJson: string;
     claudeCodeCli: {
         args: string[];
         display: string;

package/dist/cli/mcp.js

@@ -37,7 +37,7 @@ const CLIENT_LABELS = {
     gemini: "Gemini CLI",
 };
 /** Clients whose browser sign-in with Hue works against the deployed server. */
-const OAUTH_CLIENTS = ["claude-code", "codex", "conductor"];
+const OAUTH_CLIENTS = ["claude-code", "codex", "conductor", "cursor"];
 /** Toolset names Hue's MCP server accepts: `all`, its catalog groups and its curated profiles. */
 export const MCP_TOOLSETS = [
     "all",
@@ -89,11 +89,12 @@ is never written.
 
 Options:
   --client NAME   Coding agent to configure (required)
-  --auth MODE     oauth: URL only, sign in with Hue in the client (claude-code, codex and
-                  conductor; their default)
+  --auth MODE     oauth: URL only, sign in with Hue in the client (claude-code, codex,
+                  conductor and cursor; their default)
                   key: reference ${ENV_VAR} (the default for the other clients and with
-                  --read-only). Without --auth, claude-code and codex keep the choice of
-                  an existing entry, and use a key for a new one when ${ENV_VAR} is set
+                  --read-only). Without --auth, claude-code, codex and cursor keep the
+                  choice of an existing entry, and use a key for a new one when
+                  ${ENV_VAR} is set
   --read-only     Add ?read_only=true to a key configuration's URL so write tools are
                   hidden; selects a key without --auth. A sign-in connection has Read and
                   write access; use a Read key for read-only
@@ -218,9 +219,12 @@ export function renderMcpSignInSnippets(url, serverName = SERVER_NAME) {
         project ? `"${PROJECT_HEADER}" = "${project}"` : null,
     ].filter((value) => value !== null);
     const claudeCodeServer = { type: "http", url };
+    const cursorServer = { url };
     return {
         claudeCodeServer,
         claudeCodeProjectJson: json({ mcpServers: { [serverName]: claudeCodeServer } }),
+        cursorServer,
+        cursorJson: json({ mcpServers: { [serverName]: cursorServer } }),
         claudeCodeCli: {
             args: ["mcp", "add", "--transport", "http", "--scope", "user", serverName, url],
             display: `claude mcp add --transport http --scope user ${serverName} ${shellWord(url)}`,
@@ -677,11 +681,14 @@ function readClientCli(executable, args, options) {
     });
 }
 const hasAuthorization = (headers) => isRecord(headers) && Object.keys(headers).some((name) => name.toLowerCase() === "authorization");
-/** The server's HTTP entry in `./.mcp.json`; an unreadable file is reported by the write. */
-async function readClaudeProjectEntry(cwd, serverName) {
+/**
+ * The server's HTTP entry under `mcpServers` in a project file (`.mcp.json` for Claude Code,
+ * `.cursor/mcp.json` for Cursor); an unreadable file is reported by the write.
+ */
+async function readProjectEntry(cwd, file, serverName) {
     let config;
     try {
-        ({ config } = await readJsonConfig(resolve(cwd, ".mcp.json"), ".mcp.json"));
+        ({ config } = await readJsonConfig(resolve(cwd, file), file));
     }
     catch {
         return undefined;
@@ -691,7 +698,7 @@ async function readClaudeProjectEntry(cwd, serverName) {
     if (!isRecord(entry) || typeof entry.url !== "string" || !parseMcpUrl(entry.url))
         return undefined;
     const auth = hasAuthorization(entry.headers) ? "key" : "oauth";
-    return { url: entry.url, auth, source: ".mcp.json" };
+    return { url: entry.url, auth, source: file };
 }
 /**
  * The server's entry in Codex's configuration, as `codex mcp get --json` reports it: `found` with
@@ -767,7 +774,7 @@ const notOnPath = (executable, label) => `${executable} is not on PATH. Run this
 /** `auth: "oauth"` is only planned for {@link OAUTH_CLIENTS}; the caller refuses the others. */
 function planFor(client, auth, scope, url, serverName) {
     const snippets = renderMcpSnippets(url, serverName);
-    // Claude Code and Codex take the same plan shape with or without a key.
+    // Claude Code, Codex and Cursor take the same plan shape with or without a key.
     const shared = auth === "oauth" ? renderMcpSignInSnippets(url, serverName) : snippets;
     const claudeUser = {
         executable: "claude",
@@ -810,8 +817,8 @@ function planFor(client, auth, scope, url, serverName) {
                 kind: "file",
                 file: join(".cursor", "mcp.json"),
                 key: "mcpServers",
-                entry: snippets.cursorServer,
-                snippet: snippets.cursorJson,
+                entry: shared.cursorServer,
+                snippet: shared.cursorJson,
             };
         case "vscode":
             return {
@@ -842,8 +849,8 @@ function planFor(client, auth, scope, url, serverName) {
 /**
  * The authentication used without `--auth`, and the line saying why. A client that can sign in
  * does, unless a key is asked for: read-only access (`--read-only`, or `read_only=true` in
- * `--url`), which a sign-in connection does not have. For Claude Code and Codex, an existing entry
- * keeps its choice, so rerunning the command, to change `--toolsets` for instance, never swaps a
+ * `--url`), which a sign-in connection does not have. For Claude Code, Codex and Cursor, an existing
+ * entry keeps its choice, so rerunning the command, to change `--toolsets` for instance, never swaps a
  * working setup; a key keeps its `read_only`. A new entry uses a key when `HUE_MCP_KEY` is set in
  * `env`; only the variable's presence is checked. Conductor signed in by default before and keeps
  * doing so: its agents read the login-shell environment Conductor captures, not this shell's. The
@@ -903,10 +910,15 @@ function nextSteps(client, auth, serverName, project, scope, readOnly) {
                         `If Codex did not open Hue in your browser, run: codex mcp login ${serverName}`,
                         `${approve} Then start a new Codex session, which loads ${serverName}.`,
                     ]
-                    : [
-                        `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${serverName}'s authentication action. ${approve}`,
-                        "Start a new agent session if the Hue tools do not appear. Hue has not yet verified signed-in Conductor end to end; if the tools still do not load, rerun with --auth key.",
-                    ];
+                    : client === "cursor"
+                        ? [
+                            `Turn on ${serverName} in Cursor's MCP settings and use its login action, or run: cursor-agent mcp login ${serverName}`,
+                            approve,
+                        ]
+                        : [
+                            `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${serverName}'s authentication action. ${approve}`,
+                            "Start a new agent session if the Hue tools do not appear. Hue has not yet verified signed-in Conductor end to end; if the tools still do not load, rerun with --auth key.",
+                        ];
     else if (client === "vscode")
         lines = [
             `${label} prompts for the key (input ${INPUT_ID}) when the server starts; paste the ${ENV_VAR} value that hue login stored in .env.hue.`,
@@ -969,9 +981,7 @@ export async function runMcpCommand(argv, io = {}) {
     if (explicitAuth !== undefined && explicitAuth !== "key" && explicitAuth !== "oauth")
         return fail(`--auth must be key or oauth.\n\n${MCP_USAGE}`, 2);
     if (explicitAuth === "oauth" && !OAUTH_CLIENTS.includes(clientId))
-        return fail(clientId === "cursor"
-            ? "--auth oauth is not available for cursor: Hue does not yet accept Cursor's sign-in callback. Use a key (the default), or sign in from claude-code or codex."
-            : `--auth oauth is available for ${OAUTH_CLIENTS.join(", ")}. Use a key (the default) for ${clientId}.`, 2);
+        return fail(`--auth oauth is available for ${OAUTH_CLIENTS.join(", ")}. Use a key (the default) for ${clientId}.`, 2);
     const scope = parsed.values.scope ?? "project";
     if (scope !== "project" && scope !== "user")
         return fail(`--scope must be project or user.\n\n${MCP_USAGE}`, 2);
@@ -1005,11 +1015,13 @@ export async function runMcpCommand(argv, io = {}) {
             ? "read_only in --url"
             : undefined;
     // Without --auth or read_only, an existing entry keeps its choice. A user-scope `claude mcp add`
-    // refuses a name it already has, and Conductor keeps its default, so only these two are read.
+    // refuses a name it already has, and Conductor keeps its default, so only these three are read.
     let existing;
     if (explicitAuth === undefined && !parsed.values["read-only"] && !urlReadOnly) {
         if (clientId === "claude-code" && scope === "project")
-            existing = await readClaudeProjectEntry(cwd, serverName);
+            existing = await readProjectEntry(cwd, ".mcp.json", serverName);
+        else if (clientId === "cursor")
+            existing = await readProjectEntry(cwd, join(".cursor", "mcp.json"), serverName);
         else if (clientId === "codex") {
             // Without codex on PATH nothing is run, so nothing Codex holds is replaced. With it, an
             // entry that cannot be read may hold either a key or a sign-in, so the command does not

package/dist/cli/traces-import-convert.d.ts

@@ -1,10 +1,12 @@
 /**
- * The conversions behind `hue traces import prepare`: a source file is recognized by its content
- * (an OTLP/JSON trace export, a complete Langfuse observation export or a text ATIF export),
- * each trace becomes OTLP/JSON entries, one span each, that keep the recorded ids, hierarchy,
- * timestamps, content, errors and usage, and the entries are packed into deterministic gzip
- * batches. Nothing here depends on where a file sat or what it was called: a renamed or repacked
- * bundle converts to byte-identical batches, so the manifest's digests name the same import.
+ * The conversions behind `hue traces import prepare` that predate the format registry
+ * (`import-formats/registry.ts`, which recognizes each value and hands it to its format): OTLP/JSON
+ * spans kept as recorded, complete Langfuse observation exports and text ATIF exports, each trace
+ * as OTLP/JSON entries, one span each, that keep the recorded ids, hierarchy, timestamps,
+ * content, errors and usage; the shared attribute, large-value and JSON helpers; and the packing
+ * of entries into deterministic gzip batches and the manifest. Nothing here depends on where a
+ * file sat or what it was called: a renamed or repacked bundle converts to byte-identical
+ * batches, so the manifest's digests name the same import.
  */
 export declare const traceImportFormats: readonly ["otlp_json", "langfuse_observations", "atif"];
 export type TraceImportFormat = (typeof traceImportFormats)[number];
@@ -89,15 +91,19 @@ export interface PreparedBlob {
 }
 export interface ConvertedTrace {
     traceId: string;
-    format: TraceImportFormat;
+    /** The id of the format that read the trace (`import-formats/registry.ts`). */
+    format: string;
     entries: ImportEntry[];
     blobs: PreparedBlob[];
+    /** Who the trace ran for, read from its entries as Hue reads them (`import-formats/identity.ts`). */
     identity?: TraceIdentity;
     origin: TraceImportOrigin;
     /** The SHA-256 of every source file that held part of the trace. */
     sourceDigests: Set<string>;
     remappedTraceId: boolean;
     remappedSpans: number;
+    /** The rules that supplied instants the source did not record (`import-formats/rows.ts`). */
+    inferredTiming?: string[];
 }
 /** A trace, span or file that was not converted, and why. */
 export interface Refusal {
@@ -106,7 +112,21 @@ export interface Refusal {
 }
 export declare class ConversionError extends Error {
 }
+/**
+ * A failure that refuses only what was being read: a ConversionError as itself, and a RangeError
+ * (a value too large or nested too deep for a reader to walk) as one. Anything else is a defect
+ * and is undefined, for the caller to rethrow.
+ */
+export declare function conversionFailure(error: unknown): ConversionError | undefined;
+/** How deep a value read from a source may nest: far beyond any export's records, and well
+ * inside what the readers and serializers that walk a value can follow. */
+export declare const MAX_SOURCE_NESTING = 512;
+/** Whether a parsed JSON value nests deeper than `max` levels, walked without recursion and
+ * holding only the path to the value being looked at. */
+export declare function nestedTooDeep(value: unknown, max?: number): boolean;
 export declare const sha256Hex: (value: string | Uint8Array) => string;
+export declare const digestHex: (text: string, length: number) => string;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
 /**
  * JSON text parsed with every integer too large for a JavaScript number kept as its decimal
  * text, so an OTLP timestamp written as a number keeps its nanoseconds. `unsafeIntegers` says
@@ -116,29 +136,20 @@ export declare function parseJsonText(text: string): {
     value: unknown;
     unsafeIntegers: boolean;
 };
+/** JSON text a record holds (metadata values, tool arguments, a column a warehouse stores as text)
+ * parsed as {@link parseJsonText} parses it; text nested deeper than {@link MAX_SOURCE_NESTING}
+ * throws, so the caller keeps it as the text it is. */
+export declare function parseNestedJsonText(text: string): {
+    value: unknown;
+    unsafeIntegers: boolean;
+};
+/** Langfuse's experiment and evaluator environments (`sdk-experiment`, `langfuse-…`): traffic
+ * Langfuse itself marks as evaluation. */
+export declare const langfuseEvaluationEnvironment: (environment: unknown) => boolean;
 /** Refuses a source value that JavaScript or OTLP cannot retain exactly; never omits it. */
 export declare function validateSource(value: JsonValue, depth?: number): void;
 /** JSON.parse otherwise loses duplicate members and can round decimal argument values. */
 export declare function validateJsonText(raw: string): void;
-export type DetectedSource = {
-    format: "otlp_json";
-    envelopes: Record<string, unknown>[];
-} | {
-    format: "langfuse_observations";
-    observations: Record<string, JsonValue>[];
-    envelope: Record<string, JsonValue>;
-    unsafeIntegers: boolean;
-} | {
-    format: "atif";
-    text: string;
-    document: unknown;
-    unsafeIntegers: boolean;
-} | {
-    format: "unsupported";
-    reason: string;
-};
-/** What a file holds, read from its content alone; never from its name. */
-export declare function detectFormat(bytes: Uint8Array): DetectedSource;
 export declare function anyValue(value: JsonValue): OtlpValue;
 /** The large values one trace stores apart from its spans, each once by digest. */
 export declare class BlobSink {
@@ -166,25 +177,41 @@ export declare class AttributeList {
     json(key: string, value: unknown): void;
     finish(): OtlpAttribute[];
 }
-/** Gathers the spans of OTLP/JSON exports by trace, across files: an export writes a trace's
- * spans in the requests that carried them, which need not be one file. */
+/** The collector key of the formats that keep OTLP spans as recorded (OTLP/JSON, binary OTLP,
+ * Jaeger API v3): one {@link OtlpTraceCollector} gathers their spans together. */
+export declare const OTLP_SPANS = "otlp_spans";
+/** Gathers the spans of OTLP/JSON exports by trace, across files and the formats that carry
+ * them: an export writes a trace's spans in the requests that carried them, which need not be one
+ * file. Each trace is named by the format that read its first span. */
 export declare class OtlpTraceCollector {
     private readonly traces;
-    /** Adds every span of the envelopes; the spans refused, with their reasons. */
-    add(envelopes: readonly Record<string, unknown>[], sourceDigest: string): Refusal[];
+    /** Adds every span of the envelopes `format` read; the spans refused, with their reasons. */
+    add(envelopes: readonly Record<string, unknown>[], sourceDigest: string, format: string): Refusal[];
+    /** Refuses the trace a span names (its id as recorded), whatever else of it is read; a span
+     * that names no trace is refused alone. */
+    refuse(traceIdValue: unknown, reason: string): Refusal;
     private addSpan;
+    private draft;
     /** Every trace gathered so far, spans in time order, and the traces refused whole. */
     finish(): {
         traces: ConvertedTrace[];
         refused: Refusal[];
     };
 }
+/** A recorded span's string values over the inline limit stored apart from it, listed beside
+ * any values its exporter already listed. */
+export declare function offloadOtlpValues(attributes: OtlpAttribute[], blobs: BlobSink): OtlpAttribute[];
 export declare function unixNano(value: JsonValue | undefined): string;
+/** JSON text with object keys sorted: equal for equal values whatever their key order. */
+export declare const canonicalJson: (value: JsonValue) => string;
 /** Gathers Langfuse observations by trace across files and converts each trace as Hue's reader
  * converts an observation export: one span per observation, the record kept whole. */
 export declare class LangfuseTraceCollector {
     private readonly traces;
     add(observations: readonly Record<string, JsonValue>[], envelope: Record<string, JsonValue>, sourceDigest: string): void;
+    /** Refuses a trace by its Langfuse id, whatever else of it is read. */
+    refuse(traceId: string, reason: string, sourceDigest: string): void;
+    private draft;
     finish(): {
         traces: ConvertedTrace[];
         refused: Refusal[];
@@ -195,6 +222,13 @@ export declare const MAX_ATIF_FILE_BYTES: number;
 export declare const MAX_ATIF_SPANS = 2000;
 /** Retains nanoseconds and requires an explicit timezone, valid calendar date and OTLP uint64. */
 export declare function atifUnixNano(value: string): string;
+/** An ATIF document as read: its exact text, the parsed value and whether the text held an
+ * integer JavaScript cannot represent exactly. */
+export interface AtifSource {
+    text: string;
+    document: unknown;
+    unsafeIntegers: boolean;
+}
 /**
  * A text ATIF v1.7 or v1.8 export as one trace: an agent span for the run, a model span per
  * agent step with the conversation so far, a tool span per call under it, and an embedded
@@ -203,9 +237,7 @@ export declare function atifUnixNano(value: string): string;
  * document stays on the root; each model and tool span keeps its own record. ATIF supplies step
  * instants, not call durations: model and tool spans are zero-duration point spans.
  */
-export declare function convertAtifExport(source: Extract<DetectedSource, {
-    format: "atif";
-}>, rawBytes: number): ConvertedTrace;
+export declare function convertAtifExport(source: AtifSource, rawBytes: number): ConvertedTrace;
 export interface PreparedBatch {
     sha256: string;
     body: Uint8Array;