@hue-run/sdk 0.20.8 → 0.21.1

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.8`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.21.1`, `@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.
 
@@ -193,19 +193,19 @@ for staging). Hue's Settings page does not show these snippets; this command kee
   write** access to every active project in the organization the consent page names, within your
   role, so an agent first calls `list_projects` and passes the chosen project's id as `project_id`.
   The approval lasts 30 days; then sign in again. Sign-in covers the MCP server only: tracing and
-  `hue eval` still use a project key as `HUE_API_KEY`. It is available for `claude-code`, `codex`
-  and `conductor`. Hue does not yet accept Cursor's sign-in callback, so `cursor` and the other
-  clients use a key.
+  `hue eval` still use a project key as `HUE_API_KEY`. It is available for `claude-code`, `codex`,
+  `conductor` and `cursor`; the other clients use a key.
 - `key` references the `HUE_MCP_KEY` environment variable, which `hue login` stores in
   `.env.hue`. A key value is never written. Use a key for read-only access (a **Read** key, which
   only `hue login --keys coding-agent` accepts), for a run that cannot complete a browser sign-in
   (CI, `claude -p`), or for access that must outlast 30 days.
 
-Without `--auth`, `claude-code`, `codex` and `conductor` sign in and the other clients use a key.
-`--read-only` (or `read_only=true` in `--url`) selects a key. Otherwise `claude-code` and `codex`
-keep the choice of the server's existing entry, in `./.mcp.json` or as `codex mcp get` reports it,
-so a rerun that changes `--toolsets` keeps a key and its `read_only`; for a new entry they use a
-key when `HUE_MCP_KEY` is set (only its presence is checked). When `codex` is on `PATH` but `codex mcp get` fails
+Without `--auth`, `claude-code`, `codex`, `conductor` and `cursor` sign in and the other clients
+use a key. `--read-only` (or `read_only=true` in `--url`) selects a key. Otherwise `claude-code`,
+`codex` and `cursor` keep the choice of the server's existing entry, in `./.mcp.json`,
+`./.cursor/mcp.json` or as `codex mcp get` reports it, so a rerun that changes `--toolsets` keeps a
+key and its `read_only`; for a new entry they use a key when `HUE_MCP_KEY` is set (only its
+presence is checked). When `codex` is on `PATH` but `codex mcp get` fails
 for another reason, the command asks for `--auth` rather than guess which to keep. `conductor` keeps signing in, since
 its agents read the login-shell environment Conductor captures rather than your terminal's. The
 command names its choice on stderr; pass `--auth` to replace an entry as given.
@@ -253,7 +253,7 @@ reviewed cases `case_id`, environment versions `environment_version_id`, and tra
 | `claude-code` | Merges `mcpServers.hue` into `./.mcp.json`. `--scope user` runs `claude mcp add --transport http --scope user hue URL --header 'Authorization: Bearer ${HUE_MCP_KEY}'` when `claude` is on `PATH`, otherwise prints it. | Merges `mcpServers.hue` with only `type` and `url` into `./.mcp.json`; `--scope user` runs `claude mcp add --transport http --scope user hue URL`. Then restart Claude Code, run `/mcp`, select `hue` and choose **Authenticate**. |
 | `codex` | Runs `codex mcp add hue --url URL --bearer-token-env-var HUE_MCP_KEY`, or prints the `[mcp_servers.hue]` TOML block for `~/.codex/config.toml`. | Runs `codex mcp add hue --url URL`, which signs in at once and waits up to 5 minutes for the browser; without `--auth` and outside a terminal (CI, an agent's shell tool) the command prints it instead. A sign-in that does not finish leaves the server registered, and `codex mcp login hue` signs in. Then start a new Codex session. The printed TOML block keeps its URL bare and sends the selection as the `X-Hue-MCP-Toolsets` header. |
 | `conductor` | Runs the Claude Code user-scope and Codex key commands above. | Runs `claude mcp add --transport http --scope user hue URL` and `codex mcp add hue --url URL` (printed outside a terminal, as for `codex`). Then use `hue`'s authentication action in Conductor's MCP status (the plug icon or `/mcp-status`). |
-| `cursor` | Merges `mcpServers.hue` into `./.cursor/mcp.json` with `${env:HUE_MCP_KEY}`. | Refused. |
+| `cursor` | Merges `mcpServers.hue` into `./.cursor/mcp.json` with `${env:HUE_MCP_KEY}`. | Merges `mcpServers.hue` with only `url` into `./.cursor/mcp.json`. Then turn on `hue` in Cursor's MCP settings and use its login action, or run `cursor-agent mcp login hue`. |
 | `vscode` | Merges `servers.hue` and the `hue-mcp-key` password input into `./.vscode/mcp.json`. | Refused. |
 | `windsurf` | Prints the `serverUrl` snippet for `~/.codeium/windsurf/mcp_config.json`; nothing is written to the home directory. | Refused. |
 | `gemini` | Runs `gemini mcp add --scope user --transport http hue URL --header 'Authorization: Bearer ${HUE_MCP_KEY}'`, or prints it. | Refused. |
@@ -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.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
+npx -y @hue-run/sdk@0.21.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.21.1 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.8.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.21.1.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.8.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.21.1.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.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>
+npx -y @hue-run/sdk@0.21.1 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.21.1 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.21.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.21.1 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.8 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.21.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -834,21 +834,28 @@ former; a case failed for its telemetry has `state: "error"`,
 Hue-owned `world_outcome` checks are graded after the world seals. An experiment always covers
 every case of the saved version; there is no case subset.
 
-`--judges` requests the run's pinned
-`llm_judge` evaluators after outputs upload, before verdict polling. It is off by default and
-works in direct, simulation and worker modes. Requests use Hue's hosted judge budget;
+`hue eval` runs up to four cases at a time by default in one-shot and worker modes.
+`--concurrency 1` runs cases serially. Any explicit `--concurrency` value from 1 to 100 takes precedence.
+Each case keeps its own files, environment and checkpoint.
+
+The CLI requests the run's pinned `llm_judge` evaluators by default after outputs upload,
+before verdict polling, in direct, simulation and worker modes. `--no-judges` skips these requests;
+`--judges` remains accepted for existing commands. Requests use Hue's hosted judge budget;
 Hue applies its admission controls to new jobs. An accepted request remains replayable if the
-budget is later disabled. Cases without stored output are excluded, and combining
-`--judges` with `--no-output` is refused. `--check` creates no judge jobs.
+budget is later disabled. Cases without stored output are excluded. `--no-output` skips judge
+requests, and explicitly combining `--judges` with `--no-output` is refused. Without a pinned
+`llm_judge`, the CLI requests no model jobs. Creating a judge alone does not start one.
+`--check` creates no judge jobs.
 
-With `--judges --wait 0`, the CLI requests the jobs and returns their current verdict state;
+With `--wait 0`, the CLI requests the jobs and returns their current verdict state;
 pending jobs continue in Hue. Uploaded outputs are checkpointed before the attempt or worker
 queue is marked completed. If this handoff or dispatch fails, or its acknowledgement is lost,
 rerun the unchanged command with the same checkpoint directory. The CLI resumes judging the uploaded
-outputs without invoking the agent, using the same idempotency keys. After dispatch succeeds,
+outputs without invoking the agent, using the same idempotency keys. Changing to `--no-judges`
+or `--no-output` while that handoff is pending stops before a new agent run. After dispatch succeeds,
 the next ordinary invocation starts a new run as usual.
 
-`--worker --judges` discards cancelled or released handoffs. Once judge requests succeed, a
+`--worker` discards cancelled or released judge handoffs. Once judge requests succeed, a
 verdict-read failure is logged and the worker keeps accepting runs.
 
 `--command "<shell command>"` spawns the command once per case with the world's environment

package/EVALUATIONS.md

@@ -184,7 +184,7 @@ Scorer deferral shipped in TypeScript `0.3.1`: the local runner executes only th
 
 `world_outcome` pins (`hue.conversion_outcome.v1` and `.v2`, and the `hue.outcome_assertions.v2` and `.v3` case-outcome evaluators, `.v3` with its pinned judge in `config.judge`) run inside Hue and need no local callback or executable source digest. A supporting server owns their execution from saved world evidence. Legacy `local_code` pins still require the exact registered callback; changing the worker cannot convert those immutable pins into hosted ones.
 
-Manual results require a human session. Hosted model-judge dispatch is explicit: call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. Hue checks its judge budget when admitting new requests. `getJudgeBudget()` reports its current state, and on current servers the organization's monthly AI budget as `organizationBudget`, but replay an interrupted request with the same key and body even if that state changed. The [`hue eval --judges`](./CLI.md#evaluate-an-agent-against-a-case) option performs this dispatch after outputs upload; it is off by default. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
+Manual results require a human session. Hosted model-judge dispatch is explicit: call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. Hue checks its judge budget when admitting new requests. `getJudgeBudget()` reports its current state, and on current servers the organization's monthly AI budget as `organizationBudget`, but replay an interrupted request with the same key and body even if that state changed. [`hue eval`](./CLI.md#evaluate-an-agent-against-a-case) dispatches pinned model judges by default after outputs upload; `--no-judges` skips them. Creating or publishing a judge alone starts no model job. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
 
 When present, the budget's `authentication` reports credential resolution only. An
 `available` status or `configured: true` does not prove that a provider accepted the

package/README.md

@@ -82,9 +82,9 @@ claim. Setup never enables content capture or creates a simulation, Hue Run, eva
 or remote execution. See the [setup CLI contract](./CLI.md) for the supported shapes and release gates.
 
 For an existing account, `hue mcp install --client claude-code` (or `codex`, `conductor`,
-`cursor`, `vscode`, `windsurf`, `gemini`) writes the Hue MCP configuration. For Claude Code, Codex
-and Conductor it holds only the URL, and you sign in with Hue in the client; for the other clients,
-`--read-only` and `--auth key` it references `HUE_MCP_KEY` (VS Code prompts for the key).
+`cursor`, `vscode`, `windsurf`, `gemini`) writes the Hue MCP configuration. For Claude Code, Codex,
+Conductor and Cursor it holds only the URL, and you sign in with Hue in the client; for the other
+clients, `--read-only` and `--auth key` it references `HUE_MCP_KEY` (VS Code prompts for the key).
 `hue login` validates keys created in Hue Settings and stores them in `.env.hue` without printing
 them. See [Store project keys](./CLI.md#store-project-keys) and
 [Install the MCP for your coding agent](./CLI.md#install-the-mcp-for-your-coding-agent).
@@ -202,6 +202,22 @@ helpers (`setInput`, `setOutput`, `tool` arguments and results, `recordMessages`
 that is not JSON, such as a `Date` or a class instance, is omitted with an instrumentation failure
 while the callback result is returned unchanged.
 
+### Tool endpoint evidence
+
+Since TypeScript `0.21.0`, `ToolOptions` accepts an optional `endpoint`: `{ url, source, method?, captureQueryParameters? }`.
+Use the actual HTTP(S) request URL, client config URL or receipt URL; set `source` to `request`,
+`client_config` or `receipt`. Supply `method` only when known. With content capture enabled,
+Hue records `url.full`, `hue.tool.endpoint.source` and optional `http.request.method` through the
+existing redactor (`attributes.url.full` for the URL). URL userinfo and fragments are removed;
+query values are omitted unless their names appear in `captureQueryParameters`. Credential names
+are rejected even if allowlisted. Duplicate and empty allowed query values remain intact.
+
+Metadata-only mode omits endpoint evidence. Invalid evidence is omitted and counted without
+changing the tool's result or exception. This helper does not observe HTTP automatically or infer
+account identifiers. Do not supply secret-bearing URL paths, and preserve existing masking of
+account identifiers. See the [setup skill](../../skills/hue/SKILL.md#http-tool-endpoint-evidence)
+for dispatcher integration and source checkout requirements.
+
 ## Images, documents and audio
 
 Hue stores the bytes of images, documents and audio apart from the spans and log records that
@@ -536,8 +552,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.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
+npx -y @hue-run/sdk@0.21.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.21.1 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
@@ -588,6 +604,79 @@ npx -y @hue-run/sdk@latest traces import upload ./exports.hue-import --authoriza
 See [Import a bundle of existing traces](CLI.md#import-a-bundle-of-existing-traces) for the
 formats, the report, what Hue refuses and the exit codes.
 
+## Sub-agents
+
+Run a sub-agent with `hue.subagent(name, callback, options)`, inside the tool call that starts it:
+
+```ts
+const findings = await hue.tool("research", { topic }, () =>
+  hue.subagent(
+    "researcher",
+    async () => {
+      const notes = await hue.model("gpt-5-mini", () => callModel(topic), { provider: "openai" });
+      return hue.tool("summarize", notes, () => summarize(notes));
+    },
+    { input: topic },
+  ),
+);
+```
+
+The sub-agent runs inside one `invoke_agent researcher` span with `gen_ai.operation.name`
+`invoke_agent`, `gen_ai.agent.name` `researcher` and `hue.agent.role` `subagent`. That span is a
+child of the active span, here the `execute_tool research` span, and the sub-agent's own model and
+tool spans are its children, so Hue scopes them to the sub-agent. Sub-agents nest: a sub-agent's
+tool can start another. The span is `INTERNAL` unless `options.kind` says otherwise; session, user
+and workspace identifiers are inherited unless `options` sets them. `options.input` and the
+callback's defined result are recorded as `input.value` and `output.value` when `captureContent`
+is true (a callback that calls `setOutput` keeps its own output), and errors are recorded and
+rethrown as in `withSpan`.
+
+The calling agent's role is not set for you: Hue reads roles only from the spans that state them,
+and the span a sub-agent starts under is usually a tool call, not the agent. To label the calling
+agent, give its own span the role:
+
+```ts
+await hue.withSpan("invoke_agent planner", () => runPlanner(), {
+  attributes: {
+    "gen_ai.operation.name": "invoke_agent",
+    "gen_ai.agent.name": "planner",
+    "hue.agent.role": "orchestrator",
+  },
+});
+```
+
+When the sub-agent runs in another process, send the caller's trace context with the request and
+start the sub-agent under it:
+
+```ts
+// The calling process, inside the tool call that hands the task over.
+await hue.tool("research", { topic }, async () => {
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  hue.inject(headers); // adds `traceparent` only
+  const response = await fetch(researcherUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ topic, sessionId }),
+  });
+  return response.json();
+});
+
+// The sub-agent's process, for example an Express handler.
+const { topic, sessionId } = req.body;
+const findings = await hue.subagent("researcher", () => research(topic), {
+  parentContext: hue.extract(req.headers),
+  sessionId,
+});
+```
+
+The `invoke_agent researcher` span then belongs to the caller's trace, with the caller's
+`execute_tool research` span as its parent. `hue.extract()` reads a plain header object such as
+Node's `req.headers`; pass `Object.fromEntries(request.headers)` for a Fetch `Request`. Only
+`traceparent` crosses the boundary, never the API key, baggage or the session, so pass the
+session identifier yourself as above. Accept `traceparent` only from your own services: whoever
+sets it chooses the trace the sub-agent's spans join. On an endpoint that also serves other
+callers, extract it only from authenticated internal requests and start a new trace otherwise.
+
 ## Vercel AI SDK 6
 
 AI SDK 6 accepts a per-call tracer through `experimental_telemetry`. Pass
@@ -652,8 +741,8 @@ in `finally`. Shut down a shared server client only when the application stops.
 
 The integration creates real Vercel provider, streaming and tool spans and passes
 `recordInputs` and `recordOutputs` explicitly. The installed-package verification
-tests the matching 7.0.99/1.0.99 and
-7.0.100/1.0.100 pairs. Compatible-major ranges do not mean every later release
+tests the matching 7.0.99/1.0.99, 7.0.100/1.0.100, 7.0.137/1.0.137,
+7.0.138/1.0.138 and 7.0.139/1.0.139 pairs. Compatible-major ranges do not mean every later release
 has been verified. Other OTel
 instrumentations can use `hue.tracer` directly or explicitly attach the processors
 below. Instrumentations that only use a global provider need your application's
@@ -782,7 +871,8 @@ and similar attributes on your own providers.
 
 For external parent context pass `parentContext` to `withSpan`. Across processes, use
 `hue.inject(carrier)` inside the producing span and `hue.extract(carrier)` in the worker; both
-speak W3C `traceparent` only and never include the API key or baggage. Hue registers no global
+speak W3C `traceparent` only and never include the API key or baggage. Extract it only from
+trusted internal callers, as described under [Sub-agents](#sub-agents). Hue registers no global
 propagator, so `propagation.inject()` from `@opentelemetry/api` is a no-op unless your
 application configured one. `getContext()` exposes the helper's current context for APIs taking
 an explicit context. Session, user and workspace identifiers (`sessionId` as

package/dist/cli/eval.js

@@ -92,15 +92,16 @@ Output and limits:
   --check                         One-shot: check the key, selection and agent, print what the
                                   run would do and exit without creating a run or a world
   --checkpoint-dir <path>         Private checkpoint directory (default: .hue/eval/<agent-key>)
-  --concurrency <n>               Cases in flight, 1-100 (default: 1)
+  --concurrency <n>               Cases in flight, 1-100 (default: 4)
   --trace-not-accepted <policy>   A case whose telemetry Hue did not accept in time: fail_case
                                   (default) completes it as failed with the evidence omitted;
                                   pending completes it in its true state with the trace still to
                                   arrive, which Hue attaches once its export is complete
   --timeout <seconds>             Per-case --command timeout (default: 600)
   --wait <seconds>                Verdict wait after the run finishes (default: 300)
-  --judges                        Request pinned hosted model judges after outputs upload
-                                  (off by default; uses the project's judge budget)
+  --no-judges                     Skip pinned hosted model judges (requested by default
+                                  after outputs upload; uses the project's judge budget)
+  --judges                        Request pinned judges (compatibility flag)
   -h, --help                      Show this help
 
 HUE_API_KEY must be a "Read and write" project key; it is never printed.
@@ -154,7 +155,8 @@ function parse(argv) {
                 content: { type: "boolean" },
                 "no-content": { type: "boolean", default: false },
                 "no-output": { type: "boolean", default: false },
-                judges: { type: "boolean", default: false },
+                judges: { type: "boolean" },
+                "no-judges": { type: "boolean", default: false },
                 "trace-not-accepted": { type: "string" },
                 "save-version": { type: "boolean", default: false },
                 check: { type: "boolean", default: false },
@@ -1123,6 +1125,19 @@ export async function dispatchPinnedJudges(client, experimentId, subjectIds, sig
         await dispatch();
     return count;
 }
+/** Keep the judge lock through execution so an opt-out cannot race a pending dispatch. */
+async function acquireJudgeCheckpoint(directory, projectId, baseUrl, enabled) {
+    const store = await CheckpointStore.acquire(checkpointPath(directory, ["judge-dispatch", "judge checkpoint"]), { kind: "cli-judge-dispatch", projectId, baseUrl });
+    try {
+        if (!enabled && (await store.read("pending")))
+            throw new Error("Recover the pending hosted checks with the original flags before using --no-judges or --no-output");
+        return store;
+    }
+    catch (error) {
+        await store.release();
+        throw error;
+    }
+}
 /** Durable handoff before the original attempt marker or queue acknowledgement. */
 async function checkpointJudges(judging, run, completion) {
     await judging.store.write("pending", {
@@ -1242,7 +1257,7 @@ function parseBaseline(value) {
 }
 async function runOnce(values, connection, agents, agent, hue, output, signal) {
     const client = new EvaluationClient(connection);
-    const concurrency = integer("concurrency", values.concurrency, 1, 1, 100);
+    const concurrency = integer("concurrency", values.concurrency, 4, 1, 100);
     const baselineId = parseBaseline(values.baseline);
     const mode = parseMode(values.mode);
     integer("wait", values.wait, 300, 0, 86_400);
@@ -1267,9 +1282,10 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
     // Each kind of run has its own checkpoint directory and identity: a mixed run never resumes
     // from, or is resumed by, a direct or simulation run's checkpoint.
     const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, selection.kind);
+    const judgeStore = await acquireJudgeCheckpoint(checkpointDirectory, project.id, connection.baseUrl, values.judges === true);
     const judging = values.judges
         ? {
-            store: await CheckpointStore.acquire(checkpointPath(checkpointDirectory, ["judge-dispatch", "judge checkpoint"]), { kind: "cli-judge-dispatch", projectId: project.id, baseUrl: connection.baseUrl }),
+            store: judgeStore,
             selectionDigest: digest({
                 datasetVersionId: pins.datasetVersionId,
                 scorerVersionIds: [...pins.scorerVersionIds].sort(),
@@ -1385,7 +1401,7 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
         }, baselineId, output, signal, judging);
     }
     finally {
-        await judging?.store.release();
+        await judgeStore.release();
     }
 }
 /**
@@ -1425,7 +1441,7 @@ async function checkRun(client, values, pins, selection, agent, output) {
         mode: kind,
         worldCases: kind === "direct" ? 0 : worldCases,
         directCases: kind === "direct" ? cases : cases - worldCases,
-        agent: { key: agent.key, revision: agent.revision, concurrency: values.concurrency ?? "1" },
+        agent: { key: agent.key, revision: agent.revision, concurrency: values.concurrency ?? "4" },
     };
     if (values.json)
         process.stdout.write(`${JSON.stringify({ check })}\n`);
@@ -1602,19 +1618,16 @@ async function runWorker(values, connection, agents, agent, hue, output, signal)
     const client = new ObservedClient(connection);
     const environmentClient = createEnvironmentClient(connection);
     const wait = integer("wait", values.wait, 300, 0, 86_400);
-    const concurrency = integer("concurrency", values.concurrency, 1, 1, 100);
+    const concurrency = integer("concurrency", values.concurrency, 4, 1, 100);
     let maxRuns = values["max-runs"] === undefined
         ? undefined
         : integer("max-runs", values["max-runs"], 1, 1, 1_000_000);
     const project = await client.checkConnection();
     const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, "worker", slug(agent.revision) || "dev");
+    const judgeStore = await acquireJudgeCheckpoint(checkpointDirectory, project.id, connection.baseUrl, values.judges === true);
     const judging = values.judges
         ? {
-            store: await CheckpointStore.acquire(checkpointPath(checkpointDirectory, ["judge-dispatch", "judge checkpoint"]), {
-                kind: "cli-judge-dispatch",
-                projectId: project.id,
-                baseUrl: connection.baseUrl,
-            }),
+            store: judgeStore,
             selectionDigest: digest(agent),
             source: {
                 directory: checkpointDirectory,
@@ -1787,7 +1800,7 @@ async function runWorker(values, connection, agents, agent, hue, output, signal)
         return 0;
     }
     finally {
-        await judging?.store.release();
+        await judgeStore.release();
     }
 }
 /**
@@ -1831,8 +1844,11 @@ export async function runEvalCommand(argv) {
         worker = values.worker;
         if (values.content && values["no-content"])
             throw new UsageError("Choose either --content or --no-content");
+        if (values.judges && values["no-judges"])
+            throw new UsageError("Choose either --judges or --no-judges");
         if (values.judges && values["no-output"])
             throw new UsageError("--judges requires stored case outputs; remove --no-output");
+        values.judges = !values["no-judges"] && !values["no-output"];
         // A usage error before anything is prepared or created: no run is left to recover from it.
         traceNotAcceptedPolicy(values["trace-not-accepted"]);
         json = values.json;

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/client.d.ts

@@ -83,6 +83,18 @@ export declare class HueClient {
      * provider and surface as `hue.mcp.provider` / `hue.mcp.surface`.
      */
     tool<T>(name: string, input: unknown, execute: () => Promise<T> | T, options?: ToolOptions): Promise<T>;
+    /**
+     * Runs `callback` as a sub-agent: inside an `invoke_agent {name}` span carrying
+     * `gen_ai.operation.name` `invoke_agent`, `gen_ai.agent.name` and `hue.agent.role` `subagent`.
+     * The span nests under the active span, normally the `tool()` span of the call that started
+     * the sub-agent, or under `options.parentContext`, for example `hue.extract(headers)` in
+     * another process. The sub-agent's own model and tool spans nest under it, and session, user
+     * and workspace identifiers are inherited unless `options` sets them. `options.input` and a
+     * defined result are recorded as `input.value` / `output.value` when `captureContent` is true;
+     * a callback that calls `setOutput` keeps its own output. Errors are recorded and rethrown as
+     * in `withSpan`. A blank or non-string name is recorded as `unknown` and counted.
+     */
+    subagent<T>(name: string, callback: (span: HueSpan) => Promise<T> | T, options?: SpanOptions): Promise<T>;
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
      * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,

package/dist/client.js

@@ -11,6 +11,7 @@ import { defaultResource, resourceFromAttributes } from "@opentelemetry/resource
 import { HUE_SCOPE } from "./config.js";
 import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, providerErrorDescription, } from "./provider-tools.js";
 import { toolCatalogSummary } from "./tool-definitions.js";
+import { toolEndpointAttributes } from "./tool-endpoint.js";
 import { contentLimitsOf, encodeBoundedContent, encodeContent, noopSpan, safeSpan, spanSource, } from "./safety.js";
 import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
 import { countFallback, MAX_BLOB_BYTES, newTally, sizeOf } from "./blobs.js";
@@ -387,6 +388,15 @@ export class HueClient {
         stamp("mcp.server.version", options.mcp?.version);
         stamp("hue.mcp.provider", options.mcp?.provider);
         stamp("hue.mcp.surface", options.mcp?.surface);
+        if (this.enabled && !this.closed && this.captureContent) {
+            try {
+                if (options.endpoint !== undefined)
+                    Object.assign(attributes, toolEndpointAttributes(options.endpoint));
+            }
+            catch {
+                this.instrumentationFailed();
+            }
+        }
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
@@ -398,6 +408,46 @@ export class HueClient {
             ...(options.parentContext ? { parentContext: options.parentContext } : {}),
         });
     }
+    /**
+     * Runs `callback` as a sub-agent: inside an `invoke_agent {name}` span carrying
+     * `gen_ai.operation.name` `invoke_agent`, `gen_ai.agent.name` and `hue.agent.role` `subagent`.
+     * The span nests under the active span, normally the `tool()` span of the call that started
+     * the sub-agent, or under `options.parentContext`, for example `hue.extract(headers)` in
+     * another process. The sub-agent's own model and tool spans nest under it, and session, user
+     * and workspace identifiers are inherited unless `options` sets them. `options.input` and a
+     * defined result are recorded as `input.value` / `output.value` when `captureContent` is true;
+     * a callback that calls `setOutput` keeps its own output. Errors are recorded and rethrown as
+     * in `withSpan`. A blank or non-string name is recorded as `unknown` and counted.
+     */
+    async subagent(name, callback, options = {}) {
+        let agent = name;
+        if (!isLabel(name)) {
+            agent = "unknown";
+            if (this.enabled && !this.closed)
+                this.instrumentationFailed();
+        }
+        return this.withSpan(`invoke_agent ${agent}`, async (span) => {
+            let outputSet = false;
+            const result = await callback({
+                ...span,
+                setOutput: (value) => {
+                    outputSet = true;
+                    span.setOutput(value);
+                },
+            });
+            if (result !== undefined && !outputSet)
+                span.setOutput(result);
+            return result;
+        }, {
+            ...options,
+            attributes: {
+                ...options.attributes,
+                "gen_ai.operation.name": "invoke_agent",
+                "gen_ai.agent.name": agent,
+                "hue.agent.role": "subagent",
+            },
+        });
+    }
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
      * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,

package/dist/tool-endpoint.d.ts

@@ -0,0 +1,4 @@
+import type { Attributes } from "@opentelemetry/api";
+import type { ToolEndpoint } from "./types.js";
+/** Copy evidence, never send a request or resolve an endpoint from a tool name. */
+export declare function toolEndpointAttributes(endpoint: ToolEndpoint): Attributes;

package/dist/tool-endpoint.js

@@ -0,0 +1,46 @@
+import { isCredentialKey } from "./tool-definitions.js";
+/** Copy evidence, never send a request or resolve an endpoint from a tool name. */
+export function toolEndpointAttributes(endpoint) {
+    if (!endpoint ||
+        typeof endpoint.url !== "string" ||
+        endpoint.url.length > 8192 ||
+        /[\s\\\p{Cc}]/u.test(endpoint.url) ||
+        /%(?![0-9a-f]{2})/i.test(endpoint.url) ||
+        !["request", "client_config", "receipt"].includes(endpoint.source))
+        throw new Error("Invalid tool endpoint evidence");
+    const url = new URL(endpoint.url);
+    if (!["http:", "https:"].includes(url.protocol))
+        throw new Error("Invalid tool endpoint protocol");
+    const names = endpoint.captureQueryParameters ?? [];
+    if (!Array.isArray(names) ||
+        names.length > 32 ||
+        names.some((name) => typeof name !== "string" ||
+            !/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(name) ||
+            isCredentialKey(name)))
+        throw new Error("Invalid tool endpoint query allowlist");
+    // Keep the raw pairs, including duplicates and empty values. Re-encoding or selecting the
+    // first value can turn missing, malformed or ambiguous routing evidence into a usable ID.
+    const query = url.search
+        .slice(1)
+        .split("&")
+        .filter((pair) => {
+        const key = decodeURIComponent(pair.split("=", 1)[0].replace(/\+/g, " "));
+        return names.includes(key);
+    })
+        .join("&");
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    url.search = query;
+    const attributes = {
+        "url.full": url.href,
+        "hue.tool.endpoint.source": endpoint.source,
+    };
+    if (endpoint.method !== undefined) {
+        if (typeof endpoint.method !== "string" ||
+            !/^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,32}$/.test(endpoint.method))
+            throw new Error("Invalid tool endpoint method");
+        attributes["http.request.method"] = endpoint.method;
+    }
+    return attributes;
+}

package/dist/transport.js

@@ -16,7 +16,7 @@ import { MediaDigestMemo, isMediaName } from "./inline-files.js";
 import { locateParts } from "./attachment.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { DROPPED_RECORDS_KEY, isContentKey, isTruncatedMarker, redactLog, redactSpan, TRUNCATED_KEY, truncatedMarker, withTruncatedKeys, } from "./privacy.js";
-import { sdkVersion } from "./version.js";
+import { otlpExporterVersion, sdkVersion } from "./version.js";
 /** A record's trace: a span's context, a log record's span identifiers; "" when unreadable. */
 function recordTraceId(record) {
     try {
@@ -2021,7 +2021,7 @@ class ReportingExporter {
         await this.forceFlush();
     }
 }
-// OpenTelemetry's OTLP/HTTP transport rules (otlp-exporter-base 0.222), restated because that
+// OpenTelemetry's OTLP/HTTP transport rules, restated because that
 // transport discards response headers, which Hue uses to announce features.
 const MAX_RETRIES = 5;
 const INITIAL_BACKOFF_MILLIS = 1000;
@@ -2042,7 +2042,7 @@ const RETRYABLE_NETWORK_ERRORS = new Set([
     "EHOSTUNREACH",
 ]);
 /** OpenTelemetry's exporter token, which follows Hue's in the User-Agent as it always has. */
-const OTEL_USER_AGENT = "OTel-OTLP-Exporter-JavaScript/0.222.0";
+const OTEL_USER_AGENT = `OTel-OTLP-Exporter-JavaScript/${otlpExporterVersion}`;
 function retryAfterMillis(value) {
     if (value == null)
         return undefined;

package/dist/types.d.ts

@@ -201,11 +201,21 @@ export interface McpServerInfo {
     /** Hue surface such as `google.gmail/mcp`, recorded as `hue.mcp.surface`. */
     surface?: string;
 }
-/**
- * Options for {@link HueClient.tool}. `callId` is the provider-issued tool-call
- * id; `mcp` is the MCP server that handled the call.
- */
+/** Explicit routing evidence for {@link HueClient.tool}; values come from the application. */
+export interface ToolEndpoint {
+    /** Actual HTTP(S) URL used by the tool. Never synthesize it from a tool or server label. */
+    url: string;
+    /** Where the URL was observed. Recorded as `hue.tool.endpoint.source`. */
+    source: "request" | "client_config" | "receipt";
+    /** Actual HTTP method, when known; the SDK supplies no default. */
+    method?: string;
+    /** Non-secret query names to retain, including every occurrence. All others are removed. */
+    captureQueryParameters?: readonly string[];
+}
+/** Options for {@link HueClient.tool}, including call identity and opt-in routing evidence. */
 export interface ToolOptions extends Pick<SpanOptions, "parentContext"> {
+    /** Opt-in routing evidence. Only captured with content enabled, through existing redaction. */
+    endpoint?: ToolEndpoint;
     /** Provider-issued identifier of this tool call, recorded as `gen_ai.tool.call.id`. */
     callId?: string;
     /**

package/dist/version.d.ts

@@ -1,2 +1,4 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.20.8";
+export declare const sdkVersion = "0.21.1";
+/** OTLP dependency version sent in the export User-Agent. */
+export declare const otlpExporterVersion = "0.223.0";

package/dist/version.js

@@ -1,3 +1,5 @@
 // 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.8";
+export const sdkVersion = "0.21.1";
+/** OTLP dependency version sent in the export User-Agent. */
+export const otlpExporterVersion = "0.223.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.20.8",
+  "version": "0.21.1",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -91,22 +91,22 @@
   },
   "dependencies": {
     "@babel/parser": "7.29.9",
-    "@opentelemetry/api-logs": "0.222.0",
-    "@opentelemetry/core": "2.11.0",
-    "@opentelemetry/otlp-exporter-base": "0.222.0",
-    "@opentelemetry/otlp-transformer": "0.222.0",
-    "@opentelemetry/resources": "2.11.0",
-    "@opentelemetry/sdk-logs": "0.222.0",
-    "@opentelemetry/sdk-trace": "2.11.0",
+    "@opentelemetry/api-logs": "0.223.0",
+    "@opentelemetry/core": "2.12.0",
+    "@opentelemetry/otlp-exporter-base": "0.223.0",
+    "@opentelemetry/otlp-transformer": "0.223.0",
+    "@opentelemetry/resources": "2.12.0",
+    "@opentelemetry/sdk-logs": "0.223.0",
+    "@opentelemetry/sdk-trace": "2.12.0",
     "zod": "^3.25.76 || ^4.6.5"
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.99",
+    "@ai-sdk/otel": "1.0.139",
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/context-async-hooks": "2.11.0",
+    "@opentelemetry/context-async-hooks": "2.12.0",
     "@types/bun": "1.4.2",
     "@types/node": "26.6.4",
-    "ai": "7.0.99",
+    "ai": "7.0.139",
     "ajv": "8.20.0",
     "protobufjs": "8.8.0",
     "typescript": "7.0.2"