@hue-run/sdk 0.20.7 → 0.20.8

package/CLI.md

@@ -42,7 +42,7 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.20.7`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.8`, `@opentelemetry/api@1.9.1` and
 `@opentelemetry/context-async-hooks@2.11.0`; Python setup uses its separately tested package pin.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
@@ -381,8 +381,8 @@ and Hue never receives or stores them. The command is part of the `hue` executab
 #   LANGFUSE_PUBLIC_KEY=pk-lf-...
 #   LANGFUSE_SECRET_KEY=sk-lf-...
 #   LANGFUSE_BASE_URL=https://cloud.langfuse.com
-npx -y @hue-run/sdk@0.20.7 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.7 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` come from the environment or `--env-path`
@@ -698,7 +698,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.20.7.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.8.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -709,7 +709,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.20.7.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.8.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -751,10 +751,10 @@ otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`
 production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx -y @hue-run/sdk@0.20.7 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.7 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
-npx -y @hue-run/sdk@0.20.7 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.7 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.20.8 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.20.8 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
+npx -y @hue-run/sdk@0.20.8 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.20.8 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -792,7 +792,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.7 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.8 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/README.md

@@ -536,8 +536,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.20.7 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.7 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3
@@ -610,7 +610,9 @@ installed `ai` major version once per process and throws a `TypeError` below 7.
 
 ## Vercel AI SDK 7
 
-Compatible optional peers are `ai@^7.0.99` and `@ai-sdk/otel@^1.0.99`, alongside
+Compatible optional peers are `ai@^7.0.0` and `@ai-sdk/otel@^1.0.0` (install `@ai-sdk/otel` with
+the matching patch number, for example `ai@7.0.99` with `@ai-sdk/otel@1.0.99`; each `@ai-sdk/otel`
+release depends on exactly that `ai` release), alongside
 `@opentelemetry/api@1.9.1`. For an app without global AI SDK telemetry integrations,
 configure telemetry on each agent or generation call:
 
@@ -1043,7 +1045,9 @@ receipt request. It does not flush, run your application, create a test span, or
 read captured values. `fields` reports the presence of stored normalized input,
 output, model, usage, and session data across the trace; it does not establish
 content correctness or that every possible span has arrived. Leave unknown usage
-and intentionally disabled content out of `requiredFields`.
+and intentionally disabled content out of `requiredFields`. When Hue reports the trace
+missing, `project` names the project the key searched: a trace absent there was sent with a
+different key (for example one still exported in the shell) or is not stored yet.
 
 The default budget is 10 seconds; set `timeoutMillis` up to 60,000. Only a recognized
 missing trace, HTTP 429, or HTTP 503 is retried, respecting `Retry-After` and the

package/dist/cli/login.js

@@ -220,11 +220,8 @@ async function readBoundedText(response) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/**
- * Mirrors `checkConnection()` with `GET /api/v1/projects/current`, then confirms evaluation access
- * with `GET /api/v1/datasets`. No redirects are followed.
- */
-async function checkEvaluationsKey(fetchImpl, origin, apiKey) {
+/** Mirrors `checkConnection()` with `GET /api/v1/projects/current`; `detail` is the project name. */
+async function checkProject(fetchImpl, origin, apiKey) {
     let response;
     try {
         response = await fetchImpl(`${origin}/api/v1/projects/current`, {
@@ -253,16 +250,21 @@ async function checkEvaluationsKey(fetchImpl, origin, apiKey) {
             detail: `Hue answered HTTP ${response.status} while checking the evaluations key.`,
         };
     }
-    let projectName;
     try {
         const project = JSON.parse(await readBoundedText(response));
         if (!isRecord(project) || typeof project.name !== "string")
             throw new Error("Invalid project");
-        projectName = project.name;
+        return { ok: true, detail: project.name };
     }
     catch {
         return { ok: false, rejected: false, detail: "Hue returned an unexpected project response." };
     }
+}
+/** {@link checkProject}, then confirms evaluation access with `GET /api/v1/datasets`. */
+async function checkEvaluationsKey(fetchImpl, origin, apiKey) {
+    const project = await checkProject(fetchImpl, origin, apiKey);
+    if (!project.ok)
+        return project;
     // Every valid key reaches the project check; only a key with write access can list eval sets,
     // so a Read or Tracing only key is refused here instead of failing later in `hue eval`.
     let evaluations;
@@ -290,7 +292,7 @@ async function checkEvaluationsKey(fetchImpl, origin, apiKey) {
             rejected: false,
             detail: `Hue answered HTTP ${evaluations.status} while checking evaluation access.`,
         };
-    return { ok: true, detail: projectName };
+    return project;
 }
 /** Reads JSON-RPC messages from a JSON body or a `text/event-stream` body. */
 function parseJsonRpcMessages(text, contentType) {
@@ -689,6 +691,21 @@ export async function runLoginCommand(argv, io = {}) {
             out(kind === "evaluations"
                 ? `Evaluations access accepted for project "${check.detail}".`
                 : `Coding-agent access accepted; the Hue MCP server lists ${check.detail} tools.`);
+            // Loaders such as `uv run --env-file` and dotenv keep an exported variable over the file,
+            // so a stale shell key silently sends traces to another project. Name projects, never keys.
+            if (kind === "evaluations" && env.HUE_API_KEY && env.HUE_API_KEY !== value) {
+                // The shell key only goes to the server it was exported for.
+                const shellOrigin = env.HUE_BASE_URL ?? DEFAULT_ORIGIN;
+                const shell = shellOrigin === origin ? await checkProject(fetchImpl, origin, env.HUE_API_KEY) : null;
+                const owner = !shell
+                    ? ` for ${shellOrigin}`
+                    : shell.ok
+                        ? ` for project "${shell.detail}"`
+                        : shell.rejected
+                            ? " that Hue does not accept"
+                            : " whose project could not be checked";
+                stderr.write(`Warning: this shell already exports a different HUE_API_KEY${owner}. It takes precedence over ${envDisplay} (project "${check.detail}") in tools that load env files without overriding them; unset it before running the application.\n`);
+            }
         }
         if (!failure) {
             const text = mergeEnvText(envFile.text, updates);
@@ -738,12 +755,55 @@ export async function runLoginCommand(argv, io = {}) {
     }
     if (failure)
         return fail(failure.message, failure.code);
-    out("Next steps:");
+    const steps = [];
     if (stored.includes("coding-agent"))
         // `hue mcp install` defaults to production; a non-default origin needs its own endpoint.
         // Without --auth it configures sign-in unless HUE_MCP_KEY is exported, so name the key stored.
-        out(`  hue mcp install --client claude-code --auth key${mcpUrl === mcpUrlForOrigin(DEFAULT_ORIGIN) ? "" : ` --url ${mcpUrl}`}`);
-    if (stored.includes("evaluations"))
-        out(`  hue eval --case "<name>" ./hue-agent.ts${envDisplay === DEFAULT_ENV_FILE ? "" : ` --env-file ${envDisplay}`}`);
+        steps.push(`hue mcp install --client ${(await detectMcpClient(cwd)) ?? "<claude-code|codex|conductor|cursor|vscode|windsurf|gemini>"} --auth key${mcpUrl === mcpUrlForOrigin(DEFAULT_ORIGIN) ? "" : ` --url ${mcpUrl}`}`);
+    if (stored.includes("evaluations")) {
+        const agent = await detectEvalAgent(cwd);
+        if (agent)
+            steps.push(`hue eval --case "<name>" ${agent}${envDisplay === DEFAULT_ENV_FILE ? "" : ` --env-file ${envDisplay}`}`);
+    }
+    if (steps.length > 0) {
+        out("Next steps:");
+        for (const step of steps)
+            out(`  ${step}`);
+    }
     return 0;
 }
+/** Client configuration present in the repository root; `hue mcp install` writes the first three. */
+const MCP_CLIENT_MARKERS = [
+    ["claude-code", ".mcp.json"],
+    ["cursor", ".cursor"],
+    ["vscode", ".vscode"],
+    ["claude-code", ".claude"],
+    ["codex", ".codex"],
+    ["gemini", ".gemini"],
+    ["windsurf", ".windsurf"],
+];
+/** The one client whose configuration the repository holds; undefined when none or several do. */
+async function detectMcpClient(cwd) {
+    const found = new Set();
+    for (const [client, marker] of MCP_CLIENT_MARKERS)
+        if (await access(join(cwd, marker)).then(() => true, () => false))
+            found.add(client);
+    return found.size === 1 ? [...found][0] : undefined;
+}
+/** Manifests in the repository root that name its language; the CLI stays outside `hue setup`. */
+const LANGUAGE_MARKERS = [
+    ["./hue-agent.ts", "tsconfig.json"],
+    ['--command "<agent start command>"', "pyproject.toml"],
+    ['--command "<agent start command>"', "requirements.txt"],
+    ['--command "<agent start command>"', "uv.lock"],
+    ['--command "<agent start command>"', "poetry.lock"],
+    // Last: a Python repository often carries a package.json for its tooling.
+    ["./hue-agent.ts", "package.json"],
+];
+/** The `hue eval` agent argument for the repository's language; undefined when it is unknown. */
+async function detectEvalAgent(cwd) {
+    for (const [agent, marker] of LANGUAGE_MARKERS)
+        if (await access(join(cwd, marker)).then(() => true, () => false))
+            return agent;
+    return undefined;
+}

package/dist/client.js

@@ -269,10 +269,12 @@ export class HueClient {
      * @throws HueTraceVerificationError for authentication, unsupported endpoint, transport or invalid response failures.
      * @throws TypeError for an invalid trace ID or options.
      */
-    verifyTrace(traceId, options = {}) {
+    async verifyTrace(traceId, options = {}) {
         if (!this.enabled)
-            return Promise.reject(new HueConnectionError("Hue telemetry is disabled"));
-        return verifyTrace(this.transport.options, traceId, options);
+            throw new HueConnectionError("Hue telemetry is disabled");
+        // Once Hue reports the trace missing, name the project this key searched so a wrong key reads
+        // differently from a trace that is not stored yet.
+        return verifyTrace(this.transport.options, traceId, options, () => this.checkConnection().catch(() => undefined));
     }
     /** The helper's current context: the innermost active Hue span, else the OpenTelemetry active context. */
     getContext() {

package/dist/receipt.d.ts

@@ -1,4 +1,4 @@
-import type { HueOptions, TraceVerification, VerifyTraceOptions } from "./types.js";
+import type { ProjectConnection, HueOptions, TraceVerification, VerifyTraceOptions } from "./types.js";
 /**
  * Thrown by {@link HueClient.verifyTrace} when verification cannot proceed: denied key, unsupported
  * or refusing server, unreachable network or an invalid receipt. A timeout is not an error; it
@@ -18,4 +18,4 @@ export declare class HueTraceVerificationError extends Error {
 /** Observe persisted evidence after the application and its exporter have finished. */
 export declare function verifyTrace(connection: Pick<HueOptions, "apiKey"> & {
     baseUrl: string;
-}, traceId: string, options?: VerifyTraceOptions): Promise<TraceVerification>;
+}, traceId: string, options?: VerifyTraceOptions, onMissing?: () => Promise<ProjectConnection | undefined>): Promise<TraceVerification>;

package/dist/receipt.js

@@ -145,14 +145,16 @@ async function pause(milliseconds, signal) {
     });
 }
 /** Observe persisted evidence after the application and its exporter have finished. */
-export async function verifyTrace(connection, traceId, options = {}) {
-    return verifyTraceAtPath(connection, traceId, options, false, fetch);
+export async function verifyTrace(connection, traceId, options = {}, onMissing) {
+    return verifyTraceAtPath(connection, traceId, options, false, fetch, undefined, onMissing);
 }
 /** @internal Dedicated receipt path for setup credentials; ordinary clients stay unchanged. */
 export async function verifySetupTrace(connection, traceId, options, fetcher, signal) {
     return verifyTraceAtPath(connection, traceId, options, true, fetcher, signal);
 }
-async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, signal) {
+async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, signal, 
+/** Looks up the project the key searched once Hue has reported the trace missing. */
+onMissing) {
     if (!validId(traceId, 32))
         throw new TypeError("traceId must be a nonzero lowercase 32-character OpenTelemetry trace ID");
     if (options === null || typeof options !== "object" || Array.isArray(options))
@@ -181,6 +183,8 @@ async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, s
     const timer = setTimeout(() => controller.abort(), timeout);
     const requestSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     let receipt = null;
+    let missing = false;
+    let lookup;
     let delay = 250;
     try {
         while (!requestSignal.aborted && performance.now() < deadline) {
@@ -204,6 +208,7 @@ async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, s
                 const body = await readJson(response);
                 if (!record(body) || body.code !== "TRACE_NOT_FOUND")
                     throw new HueTraceVerificationError("http", "This Hue server does not support trace receipts. Check the server version and baseUrl.", 404);
+                missing = true;
             }
             else {
                 await response.body?.cancel();
@@ -221,6 +226,12 @@ async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, s
             if (remaining <= 0)
                 break;
             const wait = Math.max(delay, retryAfter);
+            // Once the backoff would outlast the budget, the rest of it names the project the key
+            // searched instead of sleeping.
+            if (wait >= remaining && missing && onMissing) {
+                lookup = onMissing();
+                break;
+            }
             await pause(Math.min(wait, remaining), requestSignal);
             // A truncated backoff exhausts this call even if a timer wakes just early.
             if (wait >= remaining)
@@ -240,5 +251,13 @@ async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, s
     finally {
         clearTimeout(timer);
     }
+    if (lookup && !receipt) {
+        const project = await Promise.race([
+            lookup,
+            pause(Math.max(0, deadline - performance.now()), controller.signal),
+        ]);
+        if (project)
+            return { verified: false, receipt, project };
+    }
     return { verified: false, receipt };
 }

package/dist/transport.js

@@ -2141,12 +2141,13 @@ class OtlpHttpTransport {
             if (this.aborted)
                 throw new Error("Hue export deadline exceeded");
             const url = new URL(this.url);
-            const protocol = url.protocol;
             // Loaded on first use, as OpenTelemetry's exporter does, so importing Hue never loads http
-            // before the application's http instrumentation can patch it. A request measured before it
-            // was sent is not compressed again.
+            // before the application's http instrumentation can patch it. Each specifier is a literal:
+            // bundlers (Next.js Turbopack, webpack) cannot resolve a computed one and replace the import
+            // with a throw, so every export would fail. A request measured before it was sent is not
+            // compressed again.
             const [{ Agent: ConnectionAgent, request }, body] = await Promise.all([
-                import(protocol === "https:" ? "node:https" : "node:http"),
+                url.protocol === "https:" ? import("node:https") : import("node:http"),
                 this.body && data === this.body.data ? this.body.compressed : compress(data),
             ]);
             if (this.aborted)

package/dist/types.d.ts

@@ -390,4 +390,9 @@ export interface TraceVerification {
     verified: boolean;
     /** Latest receipt observed, or `null` when the trace was never found. */
     receipt: TraceReceipt | null;
+    /**
+     * The project the key searched, looked up when no receipt arrived: a trace missing there was
+     * sent with a different key or is not stored yet. Absent when that lookup failed.
+     */
+    project?: ProjectConnection;
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.20.7";
+export declare const sdkVersion = "0.20.8";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.20.7";
+export const sdkVersion = "0.20.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.20.7",
+  "version": "0.20.8",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -112,9 +112,9 @@
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "@ai-sdk/otel": "^1.0.99",
+    "@ai-sdk/otel": "^1.0.0",
     "@opentelemetry/api": "^1.9.1",
-    "ai": "^6.0.0 || ^7.0.99",
+    "ai": "^6.0.0 || ^7.0.0",
     "ajv": "^8.17.0"
   },
   "peerDependenciesMeta": {