@hue-run/sdk 0.11.0 → 0.11.2

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.11.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.11.2`, `@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.
 
@@ -168,12 +168,13 @@ accepted too, but Node 22 and 24 read that flag from the whole command line and
 The env file is written with mode `0600` through a temporary file and an atomic rename. Other
 lines are preserved; a symlink or a non-regular file is refused; an existing different value is
 replaced only with `--force`. Empty values, whitespace and URLs are refused before any request.
-The MCP endpoint is `https://mcp.hue.run/mcp` for `https://app.hue.run`,
-`https://mcp.staging.hue.run/mcp` for `https://staging.hue.run` and `<origin>/api/mcp` otherwise;
-plain HTTP origins are accepted for loopback test servers only. Output names variables and lengths
-(`Stored the key (NN chars) as HUE_API_KEY and HUE_MCP_KEY`), never values. When git does not ignore the env file, the command
-warns; `--gitignore` appends the file name to the `.gitignore` next to it. Exit codes: `0` stored,
-`1` failed, `2` usage error, `130` interrupted.
+The production MCP server is available only at `https://mcp.hue.run/mcp`. `hue login` uses
+`https://mcp.staging.hue.run/mcp` with `https://staging.hue.run` and `<origin>/api/mcp` for other
+development or preview origins; plain HTTP origins are accepted for loopback test servers only.
+Output names variables and lengths (`Stored the key (NN chars) as HUE_API_KEY and HUE_MCP_KEY`),
+never values. When git does not ignore the env file, the command warns; `--gitignore` appends the
+file name to the `.gitignore` next to it. Exit codes: `0` stored, `1` failed, `2` usage error, `130`
+interrupted.
 
 ## Install the MCP for your coding agent
 
@@ -187,39 +188,63 @@ for staging). Hue's Settings page does not show these snippets; this command kee
 - `key` (the default, except for `conductor`) references the `HUE_MCP_KEY` environment variable,
   which `hue login` stores in `.env.hue`. A key value is never written.
 - `oauth` configures the URL only. The client opens Hue in a browser, where you sign in and
-  approve the connection; no key or header is involved. A new sign-in connection has **Read and
+  approve the connection; no key is involved. A new sign-in connection has **Read and
   write** access to every active project in the organization you choose, within your role, so an
   agent first calls `list_projects` and passes the chosen project's id as `project_id`. 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.
 
+`--project <id-or-slug>` pins either kind of connection to one project. The command adds or
+replaces `?project=<value>` while keeping `toolsets`, and names the server `hue-<value>` so it can
+sit beside the organization-wide `hue` connection. A pinned connection's tools do not publish or
+accept `project_id`; `list_projects` returns only that project with `connection.pinned: true`.
+The printed sign-in Codex TOML keeps its URL bare and sends `X-Hue-MCP-Project` together with any
+`X-Hue-MCP-Toolsets` header. An empty pin is refused. If the selected project is inactive or the
+credential cannot reach it, Hue returns HTTP `404`; change or remove `--project`, because signing
+in again does not change the credential's reach.
+
 `--read-only` adds `?read_only=true` to a key configuration's URL, so Hue hides and rejects write
 tools whatever the key allows. A project key, with or without it, keeps reaching its one project.
 With `--auth oauth` it is refused: a sign-in connection has **Read and write** access, so use a
 **Read** project key for read-only access.
 
-`--toolsets <names>` lists only the named tools, for clients with a tool-count limit or agents that
-only read production: `observe` (the production reads: projects, traces, spans and their recorded
-content, sessions, trace checks, intents and documentation), `all`, or the groups `project`, `traces`, `evals`, `environments`,
-`intents` and `docs`, comma-separated. A key configuration adds `?toolsets=<names>` to the URL. A
-sign-in configuration keeps the URL bare and sends the `X-Hue-MCP-Toolsets` header instead,
-because toolsets are not part of the connection's identity: Claude Code stores the header, and for
-Codex the command prints the `http_headers` line to add to `~/.codex/config.toml`, since
-`codex mcp add` stores none. `--toolsets` replaces a selection already in `--url`, and a selection in `--url` is kept without
-it; otherwise `cursor` selects `observe`. `--toolsets all` lists every tool. Unknown names are refused rather than passed on, because Hue
-ignores them and would list every tool. `get_project_context` is always listed and reports the
-selection.
+`--toolsets <names>` chooses the tools the connection lists: `all`; the profiles `observe`
+(production reads), `author` (author evaluations) and `evaluate` (run an agent against a case);
+or the groups `project`, `traces`, `eval_sets`, `runs`, `judges`, `cases`, `runners`,
+`environments`, `intents` and `docs`, comma-separated. Each group holds at most 20 tools. The
+selection is added to the URL as `?toolsets=<names>`, for a key or a sign-in configuration alike.
+Without `--toolsets`, `claude-code`, `codex` and `conductor` select `all`,
+because those agents defer MCP tools behind their own tool search; `cursor`, which caps the tools
+it loads, selects `observe`; the other clients list Hue's default. The default is the production
+reads plus `search_hue_tools`, which finds every other tool the connection can call, and
+`execute_hue_tool` and `execute_hue_write_tool`, which call one by name (the write executor only
+with write access), so nothing is out of reach. `--toolsets` replaces a selection already in
+`--url`, and a selection in `--url` is kept without it. Unknown names are refused rather than
+passed on, because Hue ignores them and would list its default. `get_project_context` is always
+listed and reports the selection.
+
+MCP arguments and results name ids after their product objects. Eval tools use `eval_set_id`,
+`eval_set_version_id`, `from_eval_set_version_id` and `eval_set_case_id`; `evaluator_id`,
+`evaluator_version_id` and `evaluator_version_ids`; `run_id` and `baseline_run_id`; and
+`scoring_run_id` and `scoring_item_id`. Dispatches use `managed_run_id` and `local_run_id`,
+reviewed cases `case_id`, environment versions `environment_version_id`, and trace-check versions
+`trace_check_version_id` or `active_trace_check_version_id`. List results are named `eval_sets`,
+`evaluators`, `runs`, `scoring_runs` and `cases`, while a row's own id remains `id`.
 
 | Client | Key (`--auth key`) | Sign-in (`--auth oauth`) |
 | --- | --- | --- |
 | `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 run `/mcp` in Claude Code, 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 can start sign-in right away; `codex mcp login hue` starts or repeats it. |
+| `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 can start sign-in right away; `codex mcp login hue` starts or repeats it. 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. | The default: runs `claude mcp add --transport http --scope user hue URL` and `codex mcp add hue --url URL`. 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. |
 | `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. |
 
+Every Codex TOML block sets `supports_parallel_tool_calls = true`, so Codex runs Hue's independent
+calls in parallel rather than one at a time. `codex mcp add` has no option for it, so after
+registering with Codex the command names the line to add under `[mcp_servers.hue]`.
+
 Conductor has no MCP configuration of its own: its Claude Code and Codex agents read their user
 configuration in every workspace, so `conductor` registers the server at user scope with each CLI
 on `PATH` and prints the command for a CLI that is missing. A failing CLI does not stop the other;
@@ -228,7 +253,8 @@ through a trace read) end to end; if Hue's tools do not load after signing in, r
 again with `--auth key`.
 
 JSON files are parsed and merged: other servers, inputs and top-level fields are kept, only the
-`hue` entry is replaced, and invalid JSON (including comments) is refused together with the snippet
+selected server entry is replaced (`hue`, or `hue-<value>` with `--project`), and invalid JSON
+(including comments) is refused together with the snippet
 to add by hand. Files are written with mode `0644` through a temporary file and an atomic rename;
 symlinks are refused. `--dry-run` prints the resulting file content or commands without writing or
 running; `--print` prints only the snippet. Client CLIs run without a shell, so the
@@ -240,7 +266,7 @@ the client (VS Code prompts for the key instead). A desktop app started from the
 does not see that shell's variables, and Conductor's agents read the login-shell environment that
 Conductor captures, so sign-in is the simpler choice there. After a sign-in installation it names
 the client's authentication action. Both end with the prompt that verifies the connection:
-`Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id as project_id on each call after list_projects.` `list_projects` returns a project key's one project too. Exit codes:
+`Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id or slug as project_id on each call after list_projects.` A pinned installation instead verifies `connection.pinned: true` and omits `project_id`. `list_projects` returns a project key's one project too. Exit codes:
 `0` done or printed, `1` failed, `2` usage error.
 
 ## Deliver simulated events to a local bot
@@ -249,12 +275,10 @@ the client's authentication action. Both end with the prompt that verifies the c
 agent such as a Slack bot can be tested without a public URL, the way `stripe listen --forward-to`
 delivers webhooks. Hue signs each request as the provider does (Slack Events API requests today);
 the command pulls them, forwards each one unchanged to `--forward-to` and reports the bot's answer
-to Hue, which settles or retries the event on the provider's schedule. It needs a **listen** event
-subscription on the world or on a connection key; the subscription's id and signing secret are shown
-once when it is created. Configure the bot with that signing secret where `SLACK_SIGNING_SECRET`
-went, then start the command: Hue offers the URL verification first, and events follow once the bot
-has answered it. Event subscriptions are not yet available on `https://app.hue.run`; until the
-origin offers them, the command stops with Hue's refusal.
+to Hue. It needs a **listen** event subscription on the world or on a connection key, and the bot
+configured with that subscription's signing secret where `SLACK_SIGNING_SECRET` went. Event
+subscriptions are not yet available on `https://app.hue.run`; until the origin offers them, the
+command exits `1` with the refusal it receives.
 
 ```sh
 hue listen --subscription <id> --forward-to http://localhost:3000/slack/events --env-path .env.world
@@ -263,8 +287,8 @@ The credential is the subscription's own, read from the environment (or `--env-p
 a variable already set keeps its value): `HUE_WORLD_TOKEN` for a world's subscription or
 `HUE_CONNECTION_KEY` for a connection key's, chosen with `--credential world-token|connection-key`
 when both are set. It is never taken from the command line, where other local processes and shell
-history can read it. A project key is refused: a value equal to `HUE_API_KEY` or `HUE_MCP_KEY` exits
-2 before any request, and Hue answers any credential that is not the subscription's with `401`.
+history can read it. A project key is refused: a value equal to `HUE_API_KEY`, `HUE_MCP_KEY`,
+`HUE_PROJECT_KEY` or `HUE_SERVICE_KEY` exits 2 before any request.
 `--origin` (default `HUE_BASE_URL`, then `https://app.hue.run`) must be HTTPS, or plain HTTP on a
 loopback test server.
 
@@ -276,12 +300,13 @@ a later one is a timeout. A failing answer with `x-slack-no-retry: 1` is reporte
 retrying it. Only a successful URL verification answer's body (at most 4 KiB, for its challenge) is
 sent to Hue; any other answer body stays on this machine. Each pull waits for at most 20 seconds and
 leases up to `--max` deliveries (1 to 10, default 10), which are forwarded concurrently; the next
-pull starts once they are acknowledged, and a delivery beyond `--max` is never forwarded. A provider
-retry of an event is a new delivery and is forwarded again with its `X-Slack-Retry-Num` and
+pull starts once they are acknowledged, and a delivery beyond `--max` is never forwarded. A pull
+that answers at once with nothing new to forward is not repeated for a second. A provider retry of
+an event is a new delivery and is forwarded again with its `X-Slack-Retry-Num` and
 `X-Slack-Retry-Reason`, so the bot deduplicates by `event_id` as it does with Slack. A delivery Hue
 hands out a second time is not sent again; its recorded answer is repeated. An acknowledgement Hue
-did not answer is repeated until the delivery's lease ends, as Hue stated it (30 seconds from the
-lease).
+did not answer is repeated until the delivery's lease ends, as the pull's answer stated it, and for
+at most 30 seconds.
 
 `--forward-to` must name this machine: `localhost`, a `.localhost` name or a loopback address, and a
 name is refused unless every address it resolves to is a loopback address. `--allow-remote-forward`
@@ -292,15 +317,16 @@ bot's status and duration, and the state Hue recorded), never a body, a signatur
 credentials in error messages are replaced with `[redacted]`.
 
 Ctrl+C or `SIGTERM` stops pulling (a waiting pull is cancelled), finishes the deliveries in flight
-and acknowledges them, then exits `0`; a second Ctrl+C abandons the forwards and acknowledgements
-still in flight and exits `130`. Nothing is acknowledged before the bot answered or its window
-closed, and a lease left unacknowledged lapses into a timeout that Hue retries on the provider's
-schedule, so no event is lost and none is marked delivered unanswered. Network errors, `429`, `5xx`
+and acknowledges them, then exits `0`, no sooner than a second after the first Ctrl+C. A second
+Ctrl+C a second or more after the first abandons the forwards and acknowledgements still in flight
+and exits `130`; one within a second of the first, such as the copy `npx` forwards to the command,
+is the same stop. Nothing is acknowledged before the bot answered or its window closed; a delivery
+left unacknowledged is left to its lease. Network errors, `429`, `5xx`, an unreadable pull answer
 and another open pull for the same subscription (a second `hue listen`) are retried with backoff up
 to 30 seconds; a `Retry-After` can lengthen a wait to at most 60 seconds, never shorten it. Exit
 codes: `0` stopped, `1` Hue refused the credential, the subscription (unknown, revoked, or one that
-delivers to a request URL) or the pull itself (a redirect, another refusal or an unreadable answer),
-`2` usage error, `130` interrupted twice.
+delivers to a request URL) or the pull itself (a redirect, another refusal or an answer without
+deliveries), `2` usage error, `130` interrupted twice.
 
 ## Local state and conflicts
 
@@ -406,7 +432,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.11.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.11.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -417,7 +443,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.11.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.11.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json

package/dist/cli/eval.d.ts

@@ -27,6 +27,10 @@ export interface Output {
     /** Diagnostics; always stderr. */
     error(line: string): void;
 }
+/** Agent key from the adapter filename, or the first script-like token of a command. An
+ * interpreter is skipped with a Windows executable suffix too (`node.exe`, and `bun.exe`, as npm
+ * installs Bun on every platform). */
+export declare function derivedAgentKey(adapterFile: string | undefined, command: string | undefined): string;
 /**
  * Spawns the agent command once in its own process group and returns its trimmed stdout. A
  * timeout or Ctrl+C stops the agent the shell started, not only the shell: a survivor would still

package/dist/cli/eval.js

@@ -179,15 +179,16 @@ const INTERPRETERS = new Set([
     "zsh",
     "env",
 ]);
-/** Agent key from the adapter filename, or the first script-like token of a command. */
-function derivedAgentKey(adapterFile, command) {
+/** Agent key from the adapter filename, or the first script-like token of a command. An
+ * interpreter is skipped with a Windows executable suffix too (`node.exe`, and `bun.exe`, as npm
+ * installs Bun on every platform). */
+export function derivedAgentKey(adapterFile, command) {
     if (adapterFile)
         return slug(basename(adapterFile, extname(adapterFile)));
     const tokens = (command ?? "").trim().split(/\s+/);
     const names = tokens.map((token) => token.split(/[\\/]/).pop() ?? "");
-    const script = names.find((name) => name && !name.startsWith("-") && !INTERPRETERS.has(name.toLowerCase())) ??
-        names[0] ??
-        "";
+    const interpreter = (name) => INTERPRETERS.has(name.toLowerCase().replace(/\.(?:exe|cmd|bat)$/, ""));
+    const script = names.find((name) => name && !name.startsWith("-") && !interpreter(name)) ?? names[0] ?? "";
     return slug(basename(script, extname(script)));
 }
 function defaultRunName(agent) {

package/dist/cli/listen.d.ts

@@ -23,7 +23,7 @@ export interface ListenCommandIo {
     /** Delays between retries of a failed pull. */
     retryDelaysMs?: readonly number[];
 }
-export declare const LISTEN_USAGE = "Usage: hue listen --subscription ID --forward-to URL [--origin URL] [--env-path PATH]\n                  [--credential world-token|connection-key] [--max N] [--allow-remote-forward]\n\nDeliver a simulated world's events to a receiver on this machine. Hue's signed requests (Slack\nEvents API requests today) are pulled with the subscription's own credential, forwarded unchanged\nto --forward-to, and acknowledged with the receiver's answer. Press Ctrl+C to stop: pulls stop,\ndeliveries in flight are finished and acknowledged, and nothing unanswered is acknowledged.\n\nThe credential is read from the environment, never from the command line:\n  HUE_WORLD_TOKEN     the world token, for a subscription on one world\n  HUE_CONNECTION_KEY  the connection key, for a subscription on a connection key\nA project key (HUE_API_KEY, HUE_MCP_KEY) is refused.\n\nOptions:\n  --subscription ID       The listen subscription to deliver (its id from Hue)\n  --forward-to URL        The local receiver, for example http://localhost:3000/slack/events\n  --origin URL            Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --env-path PATH         Load a dotenv file first (--env-file also works when it exists)\n  --credential KIND       world-token or connection-key, when both variables are set\n  --max N                 Deliveries leased per pull and forwarded at once, 1 to 10 (default 10)\n  --allow-remote-forward  Allow a --forward-to host other than this machine, over https only\n  -h, --help              Show this help";
+export declare const LISTEN_USAGE = "Usage: hue listen --subscription ID --forward-to URL [--origin URL] [--env-path PATH]\n                  [--credential world-token|connection-key] [--max N] [--allow-remote-forward]\n\nDeliver a simulated world's events to a receiver on this machine. Hue's signed requests (Slack\nEvents API requests today) are pulled with the subscription's own credential, forwarded unchanged\nto --forward-to, and acknowledged with the receiver's answer. Press Ctrl+C to stop: pulls stop,\ndeliveries in flight are finished and acknowledged, and nothing unanswered is acknowledged.\n\nThe credential is read from the environment, never from the command line:\n  HUE_WORLD_TOKEN     the world token, for a subscription on one world\n  HUE_CONNECTION_KEY  the connection key, for a subscription on a connection key\nA project key (HUE_API_KEY, HUE_MCP_KEY, HUE_PROJECT_KEY or HUE_SERVICE_KEY) is refused.\n\nOptions:\n  --subscription ID       The listen subscription to deliver (its id from Hue)\n  --forward-to URL        The local receiver, for example http://localhost:3000/slack/events\n  --origin URL            Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --env-path PATH         Load a dotenv file first (--env-file also works when it exists)\n  --credential KIND       world-token or connection-key, when both variables are set\n  --max N                 Deliveries leased per pull and forwarded at once, 1 to 10 (default 10)\n  --allow-remote-forward  Allow a --forward-to host other than this machine, over https only\n  -h, --help              Show this help";
 /** A leased delivery: the exact request the provider would send. */
 interface Delivery {
     deliveryId: string;

package/dist/cli/listen.js

@@ -5,6 +5,7 @@ import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
 import { resolve } from "node:path";
 import { parseArgs, parseEnv } from "node:util";
+import { HUE_CONTROL_PLANE_VARIABLES } from "../environment/world.js";
 import { scrubCredentialText } from "../tool-definitions.js";
 import { sdkVersion } from "../version.js";
 import { envFileArgument, envFileOptions } from "./env-file.js";
@@ -32,6 +33,11 @@ const ACK_RETRY_DELAYS_MS = [250, 500, 1_000, 2_000, 4_000];
 const MAX_RETRY_AFTER_MS = 60_000;
 /** Deliveries whose answer is remembered, so a delivery Hue hands out again is not re-sent. */
 const REMEMBERED_DELIVERIES = 1_024;
+/** The least time between pulls that forwarded nothing new, so repeats cannot spin. */
+const IDLE_PULL_FLOOR_MS = 1_000;
+/** A stop request this soon after the first is the same one: under `npx`, npm forwards the
+ * terminal's SIGINT to a process group that already received it. */
+const REPEATED_STOP_MS = 1_000;
 /** Connection-level headers the local request sets for itself. */
 const HOP_BY_HOP = new Set([
     "host",
@@ -64,7 +70,7 @@ deliveries in flight are finished and acknowledged, and nothing unanswered is ac
 The credential is read from the environment, never from the command line:
   HUE_WORLD_TOKEN     the world token, for a subscription on one world
   HUE_CONNECTION_KEY  the connection key, for a subscription on a connection key
-A project key (HUE_API_KEY, HUE_MCP_KEY) is refused.
+A project key (HUE_API_KEY, HUE_MCP_KEY, HUE_PROJECT_KEY or HUE_SERVICE_KEY) is refused.
 
 Options:
   --subscription ID       The listen subscription to deliver (its id from Hue)
@@ -413,7 +419,7 @@ function selectCredential(env, choice) {
     const credential = kind === "world-token" ? worldToken : connectionKey;
     if (!credential)
         throw new UsageError(`${variable} is not set`);
-    for (const projectVariable of ["HUE_API_KEY", "HUE_MCP_KEY"])
+    for (const projectVariable of HUE_CONTROL_PLANE_VARIABLES)
         if (env[projectVariable]?.trim() === credential)
             throw new UsageError(`${variable} holds the project key in ${projectVariable}; hue listen pulls only with the subscription's world token or connection key`);
     if (kind === "world-token" && !WORLD_TOKEN.test(credential))
@@ -547,16 +553,18 @@ export async function runListenCommand(argv, io = {}) {
         accept: "application/json",
         "user-agent": `hue-sdk-typescript/${sdkVersion} hue-listen`,
     };
-    // The first stop request stops pulling and lets deliveries in flight finish; a second one
-    // abandons their acknowledgements, whose leases then lapse into timeouts.
+    // The first stop request stops pulling and lets deliveries in flight finish; a second one, a
+    // second or more later, abandons their acknowledgements, whose leases then lapse into timeouts.
     const stopping = new AbortController();
     const forced = new AbortController();
+    let stoppedAt = 0;
     const removeInterrupt = (io.onInterrupt ?? defaultOnInterrupt)(() => {
         if (!stopping.signal.aborted) {
+            stoppedAt = performance.now();
             stopping.abort();
             warn("Stopping: finishing deliveries in flight (press Ctrl+C again to abandon them).");
         }
-        else
+        else if (performance.now() - stoppedAt >= REPEATED_STOP_MS)
             forced.abort();
     });
     const remembered = new Map();
@@ -736,6 +744,7 @@ export async function runListenCommand(argv, io = {}) {
             }
         }
     };
+    /** Forwards and acknowledges one delivery; true when its request reached the receiver now. */
     const deliver = async (delivery, deadline) => {
         // Hue may hand out a delivery again (a pull whose answer was retried); its request already
         // reached the receiver, so the recorded answer is repeated and nothing is sent twice.
@@ -751,7 +760,7 @@ export async function runListenCommand(argv, io = {}) {
             : `${delivery.eventId ?? "event"}${delivery.retryNum ? ` retry ${delivery.retryNum}` : ""}`;
         if (answer === null) {
             out(`${new Date().toISOString()}  ${name} -> abandoned; not acknowledged, the lease lapses into a timeout`);
-            return;
+            return false;
         }
         if (!previous) {
             remembered.set(delivery.deliveryId, answer);
@@ -762,6 +771,7 @@ export async function runListenCommand(argv, io = {}) {
         if (result.kind === "revoked")
             fatal ??= `Subscription ${subscription} is revoked.`;
         out(`${new Date().toISOString()}  ${name}${previous ? " (repeated)" : ""} -> ${describeAnswer(answer)}; ${describeAck(result)}`);
+        return !previous;
     };
     out(`Forwarding subscription ${subscription} from ${foreign(origin)} to ${foreign(target.href)} using the ${label}. Press Ctrl+C to stop.`);
     let failures = 0;
@@ -786,9 +796,7 @@ export async function runListenCommand(argv, io = {}) {
                 continue;
             }
             failures = 0;
-            // A pull that answers empty at once, though it could wait, is not repeated at once.
-            if (ready && result.deliveries.length === 0 && performance.now() - pulledAt < 1_000)
-                await sleep(1_000, stopping.signal);
+            const waited = ready;
             if (!ready) {
                 ready = true;
                 out("Ready: waiting for events.");
@@ -797,11 +805,26 @@ export async function runListenCommand(argv, io = {}) {
                 warn(`Skipped ${result.skipped} delivery(ies) this version of @hue-run/sdk cannot forward; their leases lapse and Hue retries them.`);
             if (result.excess)
                 warn(`Hue leased ${result.excess} more delivery(ies) than --max ${max}; they are not forwarded, their leases lapse and Hue retries them.`);
-            await Promise.all(result.deliveries.map((delivery) => deliver(delivery, result.receivedAt + result.leaseLeftMs(delivery))));
+            const forwarded = await Promise.all(result.deliveries.map((delivery) => deliver(delivery, result.receivedAt + result.leaseLeftMs(delivery))));
+            // A pull that could wait but answered at once with nothing new to forward (none due, only
+            // deliveries already answered, or ones this client skips) is not repeated at once, so a
+            // Hue that hands them out again or refuses their acknowledgements is not pulled in a loop.
+            if (waited && !forwarded.includes(true) && performance.now() - pulledAt < IDLE_PULL_FLOOR_MS)
+                await sleep(IDLE_PULL_FLOOR_MS, stopping.signal);
         }
     }
     finally {
-        removeInterrupt();
+        // A repeated stop request can still arrive once the loop has ended (npm forwards Ctrl+C a few
+        // milliseconds late), and without a listener, or once the process has begun to exit, the
+        // runtime's default handler would end it by SIGINT. So the listener, and the process, stay
+        // until such a request would count as a new one: at most a second after the first.
+        const repeatable = stopping.signal.aborted
+            ? REPEATED_STOP_MS - (performance.now() - stoppedAt)
+            : 0;
+        if (repeatable > 0)
+            setTimeout(removeInterrupt, repeatable);
+        else
+            removeInterrupt();
     }
     if (fatal !== null) {
         warn(`Error: ${fatal}`);

package/dist/cli/mcp.d.ts

@@ -2,8 +2,8 @@
  * `hue mcp install`: writes or prints the coding-agent configuration for Hue's MCP server. The
  * shapes are those of Hue's published connection guide (https://docs.hue.run/agents/mcp-server),
  * kept as a separate copy here. Key configurations reference the `HUE_MCP_KEY` environment
- * variable (or a VS Code password input); sign-in configurations hold only the URL. A key value is
- * never written.
+ * variable (or a VS Code password input); sign-in configurations hold no credential. A key value
+ * is never written.
  */
 /** Streams, environment and working directory for {@link runMcpCommand}; tests inject these. */
 export interface McpCommandIo {
@@ -20,12 +20,17 @@ export declare const DEFAULT_MCP_URL = "https://mcp.hue.run/mcp";
  * lists them, after which each call takes `project_id`. It reads what needs attention and falls
  * back to recent traces, so a project without errors still proves the read path.
  */
-export declare const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id as project_id on each call after list_projects.";
-/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and the `observe` profile. */
-export declare const MCP_TOOLSETS: readonly ["all", "observe", "project", "traces", "evals", "environments", "intents", "docs"];
-/** The header that selects toolsets for a sign-in connection, whose URL must stay bare. */
+export declare const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id or slug as project_id on each call after list_projects.";
+/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and its curated profiles. */
+export declare const MCP_TOOLSETS: readonly ["all", "observe", "author", "evaluate", "project", "traces", "eval_sets", "runs", "judges", "cases", "runners", "environments", "intents", "docs"];
+/**
+ * The header form of `?toolsets=`. Only the sign-in Codex TOML uses it, as Hue's guide does, to
+ * keep that URL bare; every other configuration carries the selection in its URL.
+ */
 export declare const TOOLSETS_HEADER = "X-Hue-MCP-Toolsets";
-export declare const MCP_USAGE = "Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>\n                       [--auth key|oauth] [--read-only] [--toolsets NAMES] [--url URL]\n                       [--scope project|user] [--dry-run] [--print]\n\nConfigure a coding agent to use the Hue MCP server. A key configuration references the\nHUE_MCP_KEY environment variable; a key value is never written. A sign-in configuration holds\nonly the URL: the client opens Hue in a browser, where you approve access to the projects of\none organization.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --auth MODE     key: reference HUE_MCP_KEY (the default, except for conductor)\n                  oauth: URL only, sign in with Hue in the client (claude-code, codex and\n                  conductor; the default for conductor)\n  --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A\n                  sign-in connection has Read and write access; use a Read key for read-only\n  --toolsets NAMES\n                  List only these tools, comma-separated: observe (production reads),\n                  all, project, traces, evals, environments, intents or docs. A key\n                  configuration adds ?toolsets= to the URL; a sign-in one sends the\n                  X-Hue-MCP-Toolsets header. cursor defaults to observe; others to all\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.";
+/** 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 key configuration references the\nHUE_MCP_KEY environment variable; a key value is never written. A sign-in configuration holds\nonly the URL: the client opens Hue in a browser, where you approve access to the projects of\none organization.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --auth MODE     key: reference HUE_MCP_KEY (the default, except for conductor)\n                  oauth: URL only, sign in with Hue in the client (claude-code, codex and\n                  conductor; the default for conductor)\n  --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A\n                  sign-in connection has Read and 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.";
 /**
  * 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.
@@ -35,7 +40,7 @@ export declare function shellWord(value: string): string;
  * Canonical Hue client snippets for a key configuration; the JSON values are also the merge
  * entries for config files.
  */
-export declare function renderMcpSnippets(url: string): {
+export declare function renderMcpSnippets(url: string, serverName?: string): {
     claudeCodeServer: {
         type: string;
         url: string;
@@ -87,16 +92,14 @@ export declare function renderMcpSnippets(url: string): {
     };
 };
 /**
- * Sign-in snippets: the bare server URL, which the client uses to discover Hue's OAuth metadata,
- * and, when toolsets are selected, the header that carries them.
+ * Sign-in snippets: the server URL and nothing secret. The client discovers Hue's OAuth metadata
+ * from it and sends it, query included, on every request; the token's resource ignores the query,
+ * so `?toolsets=` and `?project=` select tools and a project here as they do for a key.
  */
-export declare function renderMcpSignInSnippets(url: string, toolsets?: string): {
+export declare function renderMcpSignInSnippets(url: string, serverName?: string): {
     claudeCodeServer: {
         type: string;
         url: string;
-        headers?: {
-            "X-Hue-MCP-Toolsets": string;
-        } | undefined;
     };
     claudeCodeProjectJson: string;
     claudeCodeCli: {
@@ -111,7 +114,7 @@ export declare function renderMcpSignInSnippets(url: string, toolsets?: string):
 };
 /**
  * Parses a comma-separated `--toolsets` value into Hue's canonical form, or returns an error.
- * Unknown names are refused: Hue ignores them and would list the whole catalog, hiding a typo.
+ * Unknown names are refused: Hue ignores them and would list its default, hiding a typo.
  */
 export declare function parseToolsets(value: string): {
     toolsets: string;
@@ -119,10 +122,19 @@ export declare function parseToolsets(value: string): {
     error: string;
 };
 /**
- * `?toolsets=` lists only the selected tools for a key configuration; commas stay readable.
- * Without a selection the parameter is removed, so the URL lists every tool.
+ * `?toolsets=` lists only the selected tools; commas stay readable. Without a selection the
+ * parameter is removed, so the connection lists Hue's default.
  */
 export declare function toolsetsMcpUrl(url: string, toolsets: string | undefined): string;
+/** Parses the id or slug used to pin a connection and derives its coexisting server name. */
+export declare function parseProject(value: string): {
+    project: string;
+    serverName: string;
+} | {
+    error: string;
+};
+/** Replaces `?project=` while preserving the URL's other selections. */
+export declare function projectMcpUrl(url: string, project: string | undefined): string;
 /** `?read_only=true` hides and rejects Hue's write tools for any key. */
 export declare function readOnlyMcpUrl(url: string): string;
 /** Validates the MCP endpoint: HTTPS, or HTTP for loopback test servers; no credentials or hash. */

package/dist/cli/mcp.js

@@ -16,7 +16,7 @@ const MAX_CONFIG_BYTES = 1024 * 1024;
  * lists them, after which each call takes `project_id`. It reads what needs attention and falls
  * back to recent traces, so a project without errors still proves the read path.
  */
-export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id as project_id on each call after list_projects.";
+export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id or slug as project_id on each call after list_projects.";
 const CLIENT_IDS = [
     "claude-code",
     "codex",
@@ -37,23 +37,48 @@ const CLIENT_LABELS = {
 };
 /** Clients whose browser sign-in with Hue works against the deployed server. */
 const OAUTH_CLIENTS = ["claude-code", "codex", "conductor"];
-/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and the `observe` profile. */
+/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and its curated profiles. */
 export const MCP_TOOLSETS = [
     "all",
     "observe",
+    "author",
+    "evaluate",
     "project",
     "traces",
-    "evals",
+    "eval_sets",
+    "runs",
+    "judges",
+    "cases",
+    "runners",
     "environments",
     "intents",
     "docs",
 ];
-/** The header that selects toolsets for a sign-in connection, whose URL must stay bare. */
+/**
+ * The header form of `?toolsets=`. Only the sign-in Codex TOML uses it, as Hue's guide does, to
+ * keep that URL bare; every other configuration carries the selection in its URL.
+ */
 export const TOOLSETS_HEADER = "X-Hue-MCP-Toolsets";
-/** Clients whose configuration selects a toolset unless `--toolsets` says otherwise. */
-const DEFAULT_TOOLSETS = { cursor: "observe" };
+/** The header form of `?project=`, used by the sign-in Codex TOML to keep its URL bare. */
+export const PROJECT_HEADER = "X-Hue-MCP-Project";
+/**
+ * Toolsets a client's configuration selects unless `--toolsets` says otherwise. Claude Code,
+ * Codex and Conductor's agents defer MCP tools behind their own tool search, so listing every tool
+ * costs them little. Cursor caps the tools it loads, so it names the production reads. The other
+ * clients list Hue's default: the production reads, and `search_hue_tools` with its executors,
+ * which reach every other tool.
+ */
+const DEFAULT_TOOLSETS = {
+    "claude-code": "all",
+    codex: "all",
+    conductor: "all",
+    cursor: "observe",
+};
+/** Codex runs a server's tool calls one at a time without it; each Hue call is independent. */
+const CODEX_PARALLEL = "supports_parallel_tool_calls = true";
 export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>
-                       [--auth key|oauth] [--read-only] [--toolsets NAMES] [--url URL]
+                       [--auth key|oauth] [--read-only] [--project ID-OR-SLUG]
+                       [--toolsets NAMES] [--url URL]
                        [--scope project|user] [--dry-run] [--print]
 
 Configure a coding agent to use the Hue MCP server. A key configuration references the
@@ -68,11 +93,16 @@ Options:
                   conductor; the default for conductor)
   --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A
                   sign-in connection has Read and write access; use a Read key for read-only
+  --project VALUE Pin the connection to one project by id or slug. Its tools omit project_id,
+                  and the server is named hue-<value> so it can coexist with an unpinned hue
   --toolsets NAMES
-                  List only these tools, comma-separated: observe (production reads),
-                  all, project, traces, evals, environments, intents or docs. A key
-                  configuration adds ?toolsets= to the URL; a sign-in one sends the
-                  ${TOOLSETS_HEADER} header. cursor defaults to observe; others to all
+                  Tools to list, comma-separated: all; the observe, author or evaluate
+                  profiles; or project, traces, eval_sets, runs, judges, cases, runners,
+                  environments, intents or docs. Added to the URL as ?toolsets=.
+                  Defaults: all for claude-code, codex and conductor,
+                  which search their own tools; observe for cursor. Without a selection
+                  Hue lists the production reads and search_hue_tools, which reaches
+                  every other tool
   --url URL       Hue MCP endpoint (default ${DEFAULT_MCP_URL})
   --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs
                   \`claude mcp add --scope user\`
@@ -96,7 +126,7 @@ export function shellWord(value) {
  * Canonical Hue client snippets for a key configuration; the JSON values are also the merge
  * entries for config files.
  */
-export function renderMcpSnippets(url) {
+export function renderMcpSnippets(url, serverName = SERVER_NAME) {
     const bearer = (reference) => `Bearer ${reference}`;
     const claudeCodeServer = {
         type: "http",
@@ -121,7 +151,7 @@ export function renderMcpSnippets(url) {
     };
     return {
         claudeCodeServer,
-        claudeCodeProjectJson: json({ mcpServers: { [SERVER_NAME]: claudeCodeServer } }),
+        claudeCodeProjectJson: json({ mcpServers: { [serverName]: claudeCodeServer } }),
         claudeCodeCli: {
             args: [
                 "mcp",
@@ -130,25 +160,25 @@ export function renderMcpSnippets(url) {
                 "http",
                 "--scope",
                 "user",
-                SERVER_NAME,
+                serverName,
                 url,
                 "--header",
                 `Authorization: Bearer \${${ENV_VAR}}`,
             ],
-            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+            display: `claude mcp add --transport http --scope user ${serverName} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
         },
         cursorServer,
-        cursorJson: json({ mcpServers: { [SERVER_NAME]: cursorServer } }),
+        cursorJson: json({ mcpServers: { [serverName]: cursorServer } }),
         codexCli: {
-            args: ["mcp", "add", SERVER_NAME, "--url", url, "--bearer-token-env-var", ENV_VAR],
-            display: `codex mcp add ${SERVER_NAME} --url ${shellWord(url)} --bearer-token-env-var ${ENV_VAR}`,
+            args: ["mcp", "add", serverName, "--url", url, "--bearer-token-env-var", ENV_VAR],
+            display: `codex mcp add ${serverName} --url ${shellWord(url)} --bearer-token-env-var ${ENV_VAR}`,
         },
-        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n`,
+        codexToml: `[mcp_servers.${serverName}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n${CODEX_PARALLEL}\n`,
         vscodeServer,
         vscodeInput,
-        vscodeJson: json({ servers: { [SERVER_NAME]: vscodeServer }, inputs: [vscodeInput] }),
+        vscodeJson: json({ servers: { [serverName]: vscodeServer }, inputs: [vscodeInput] }),
         windsurfServer,
-        windsurfJson: json({ mcpServers: { [SERVER_NAME]: windsurfServer } }),
+        windsurfJson: json({ mcpServers: { [serverName]: windsurfServer } }),
         geminiCli: {
             args: [
                 "mcp",
@@ -157,53 +187,49 @@ export function renderMcpSnippets(url) {
                 "user",
                 "--transport",
                 "http",
-                SERVER_NAME,
+                serverName,
                 url,
                 "--header",
                 `Authorization: Bearer \${${ENV_VAR}}`,
             ],
             // Single quotes keep the reference literal when a person runs this in a shell where the
             // key is exported; Gemini CLI expands ${HUE_MCP_KEY} from its settings at connection time.
-            display: `gemini mcp add --scope user --transport http ${SERVER_NAME} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+            display: `gemini mcp add --scope user --transport http ${serverName} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
         },
     };
 }
 /**
- * Sign-in snippets: the bare server URL, which the client uses to discover Hue's OAuth metadata,
- * and, when toolsets are selected, the header that carries them.
+ * Sign-in snippets: the server URL and nothing secret. The client discovers Hue's OAuth metadata
+ * from it and sends it, query included, on every request; the token's resource ignores the query,
+ * so `?toolsets=` and `?project=` select tools and a project here as they do for a key.
  */
-export function renderMcpSignInSnippets(url, toolsets) {
-    const headers = toolsets ? { [TOOLSETS_HEADER]: toolsets } : undefined;
-    const claudeCodeServer = { type: "http", url, ...(headers ? { headers } : {}) };
-    const headerArgs = toolsets ? ["--header", `${TOOLSETS_HEADER}: ${toolsets}`] : [];
+export function renderMcpSignInSnippets(url, serverName = SERVER_NAME) {
+    const parsed = new URL(url);
+    const toolsets = parsed.searchParams.get("toolsets");
+    const project = parsed.searchParams.get("project");
+    const headers = [
+        toolsets ? `"${TOOLSETS_HEADER}" = "${toolsets}"` : null,
+        project ? `"${PROJECT_HEADER}" = "${project}"` : null,
+    ].filter((value) => value !== null);
+    const claudeCodeServer = { type: "http", url };
     return {
         claudeCodeServer,
-        claudeCodeProjectJson: json({ mcpServers: { [SERVER_NAME]: claudeCodeServer } }),
+        claudeCodeProjectJson: json({ mcpServers: { [serverName]: claudeCodeServer } }),
         claudeCodeCli: {
-            args: [
-                "mcp",
-                "add",
-                "--transport",
-                "http",
-                "--scope",
-                "user",
-                SERVER_NAME,
-                url,
-                ...headerArgs,
-            ],
-            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${shellWord(url)}${toolsets ? ` --header '${TOOLSETS_HEADER}: ${toolsets}'` : ""}`,
+            args: ["mcp", "add", "--transport", "http", "--scope", "user", serverName, url],
+            display: `claude mcp add --transport http --scope user ${serverName} ${shellWord(url)}`,
         },
-        // `codex mcp add` cannot store a header; the TOML carries it and the next steps say so.
         codexCli: {
-            args: ["mcp", "add", SERVER_NAME, "--url", url],
-            display: `codex mcp add ${SERVER_NAME} --url ${shellWord(url)}`,
+            args: ["mcp", "add", serverName, "--url", url],
+            display: `codex mcp add ${serverName} --url ${shellWord(url)}`,
         },
-        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${url}"\n${toolsets ? `http_headers = { "${TOOLSETS_HEADER}" = "${toolsets}" }\n` : ""}`,
+        // Header forms of the selections, for a TOML entry that keeps its URL bare.
+        codexToml: `[mcp_servers.${serverName}]\nurl = "${projectMcpUrl(toolsetsMcpUrl(url, undefined), undefined)}"\n${headers.length ? `http_headers = { ${headers.join(", ")} }\n` : ""}${CODEX_PARALLEL}\n`,
     };
 }
 /**
  * Parses a comma-separated `--toolsets` value into Hue's canonical form, or returns an error.
- * Unknown names are refused: Hue ignores them and would list the whole catalog, hiding a typo.
+ * Unknown names are refused: Hue ignores them and would list its default, hiding a typo.
  */
 export function parseToolsets(value) {
     const names = [...new Set(value.split(",").map((name) => name.trim()))];
@@ -217,8 +243,8 @@ export function parseToolsets(value) {
     return { toolsets: names.join(",") };
 }
 /**
- * `?toolsets=` lists only the selected tools for a key configuration; commas stay readable.
- * Without a selection the parameter is removed, so the URL lists every tool.
+ * `?toolsets=` lists only the selected tools; commas stay readable. Without a selection the
+ * parameter is removed, so the connection lists Hue's default.
  */
 export function toolsetsMcpUrl(url, toolsets) {
     const parsed = new URL(url);
@@ -229,6 +255,25 @@ export function toolsetsMcpUrl(url, toolsets) {
     parsed.search = `${query ? `${query}&` : ""}toolsets=${toolsets}`;
     return parsed.href;
 }
+/** Parses the id or slug used to pin a connection and derives its coexisting server name. */
+export function parseProject(value) {
+    const project = value.trim();
+    if (!project)
+        return { error: "--project is empty. Name a project id or slug, or remove the option." };
+    if (project.length > 256 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/iu.test(project))
+        return {
+            error: "--project takes a project id or slug, using letters, numbers and hyphens.",
+        };
+    return { project, serverName: `${SERVER_NAME}-${project.toLowerCase()}` };
+}
+/** Replaces `?project=` while preserving the URL's other selections. */
+export function projectMcpUrl(url, project) {
+    const parsed = new URL(url);
+    parsed.searchParams.delete("project");
+    if (project)
+        parsed.searchParams.append("project", project);
+    return parsed.href;
+}
 /** `?read_only=true` hides and rejects Hue's write tools for any key. */
 export function readOnlyMcpUrl(url) {
     const parsed = new URL(url);
@@ -244,15 +289,15 @@ class ConfigError extends Error {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Replaces only the `hue` entry under `key`, keeping every other server and top-level field. */
-function mergeServerEntry(existing, key, entry, display) {
+/** Replaces only the selected server entry under `key`, keeping every other server and field. */
+function mergeServerEntry(existing, key, entry, display, serverName = SERVER_NAME) {
     if (existing !== undefined && !isRecord(existing))
         throw new ConfigError(`${display} must contain a JSON object.`);
     const root = existing ?? {};
     const servers = root[key];
     if (servers !== undefined && !isRecord(servers))
         throw new ConfigError(`${display}: "${key}" must be a JSON object.`);
-    return { ...root, [key]: { ...(servers ?? {}), [SERVER_NAME]: entry } };
+    return { ...root, [key]: { ...(servers ?? {}), [serverName]: entry } };
 }
 function mergeVscodeInput(root, input, display) {
     const inputs = root.inputs;
@@ -390,6 +435,7 @@ function parseMcpArguments(argv) {
             client: { type: "string" },
             auth: { type: "string" },
             "read-only": { type: "boolean", default: false },
+            project: { type: "string" },
             toolsets: { type: "string" },
             url: { type: "string" },
             scope: { type: "string" },
@@ -405,10 +451,10 @@ function displayPath(cwd, path) {
 }
 const notOnPath = (executable, label) => `${executable} is not on PATH. Run this where ${label} is installed:`;
 /** `auth: "oauth"` is only planned for {@link OAUTH_CLIENTS}; the caller refuses the others. */
-function planFor(client, auth, scope, url, toolsets) {
-    const snippets = renderMcpSnippets(url);
+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.
-    const shared = auth === "oauth" ? renderMcpSignInSnippets(url, toolsets) : snippets;
+    const shared = auth === "oauth" ? renderMcpSignInSnippets(url, serverName) : snippets;
     const claudeUser = {
         executable: "claude",
         label: "Claude Code",
@@ -479,21 +525,23 @@ function planFor(client, auth, scope, url, toolsets) {
         }
     }
 }
-function nextSteps(client, auth, toolsets) {
+function nextSteps(client, auth, serverName, project) {
     const label = CLIENT_LABELS[client];
-    const approve = "Sign in to Hue and approve the connection. It can read and write every active project in the organization you choose, within your role; for read-only access, use a Read project key with --auth key.";
+    const approve = project
+        ? `Sign in to Hue and approve the connection. It acts only on the pinned project ${project}, within your role; for read-only access, use a Read project key with --auth key.`
+        : "Sign in to Hue and approve the connection. It can read and write every active project in the organization you choose, within your role; for read-only access, use a Read project key with --auth key.";
     let lines;
     if (auth === "oauth")
         lines =
             client === "claude-code"
-                ? [`In Claude Code, run /mcp, select ${SERVER_NAME} and choose Authenticate. ${approve}`]
+                ? [`In Claude Code, run /mcp, select ${serverName} and choose Authenticate. ${approve}`]
                 : client === "codex"
                     ? [
-                        `If Codex did not open Hue in your browser, run: codex mcp login ${SERVER_NAME}`,
+                        `If Codex did not open Hue in your browser, run: codex mcp login ${serverName}`,
                         approve,
                     ]
                     : [
-                        `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${SERVER_NAME}'s authentication action. ${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")
@@ -510,10 +558,15 @@ function nextSteps(client, auth, toolsets) {
             "  set -a; . ./.env.hue; set +a",
             `An app started from the Dock or a launcher does not see that shell's variables; start ${label} from the shell${OAUTH_CLIENTS.includes(client) ? ", or sign in instead with --auth oauth" : ""}.`,
         ];
-    // `codex mcp add` stores no headers, so a sign-in toolset selection is added by hand.
-    if (auth === "oauth" && toolsets && (client === "codex" || client === "conductor"))
-        lines.push(`To list only the ${toolsets} tools in Codex, add this line under [mcp_servers.${SERVER_NAME}] in ~/.codex/config.toml:`, `  http_headers = { "${TOOLSETS_HEADER}" = "${toolsets}" }`);
-    return [...lines, "Then ask your agent:", `  ${MCP_VERIFY_PROMPT}`];
+    // `codex mcp add` has no option for it, so a registered server gets the line by hand.
+    if (client === "codex" || client === "conductor")
+        lines.push(`If codex mcp add registered ${serverName}, add this line under [mcp_servers.${serverName}] in ~/.codex/config.toml so Codex runs Hue's tool calls in parallel:`, `  ${CODEX_PARALLEL}`);
+    if (project)
+        lines.push(`If this connection returns HTTP 404, ${project} is not an active project this credential can reach. Change or remove --project; signing in again will not fix it.`);
+    const verify = project
+        ? `Use the Hue MCP: call list_projects and confirm it returns only the pinned project ${project} with connection.pinned true. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. Do not pass project_id: this connection is pinned.`
+        : MCP_VERIFY_PROMPT;
+    return [...lines, "Then ask your agent:", `  ${verify}`];
 }
 /**
  * Runs `hue mcp install` and returns the process exit code: 0 done or printed, 1 failed, 2 usage
@@ -570,11 +623,27 @@ export async function runMcpCommand(argv, io = {}) {
         return fail("A sign-in connection has Read and write access and cannot be made read-only by its URL. For read-only access, use a Read project key (--auth key), or add --read-only to a key configuration.", 2);
     if (parsed.values["read-only"])
         url = readOnlyMcpUrl(url);
-    // Toolsets are not part of the protected resource either: a sign-in URL stays bare.
-    if (auth === "oauth" && new URL(url).searchParams.has("toolsets"))
-        return fail("Leave toolsets off a sign-in URL; --toolsets sends them in a header instead.", 2);
+    // --project replaces a pin already in --url. Without it, validate and keep the URL's pin.
+    const urlProjects = new URL(url).searchParams.getAll("project");
+    let projectValue = parsed.values.project;
+    if (projectValue === undefined && urlProjects.length) {
+        const trimmed = urlProjects.map((value) => value.trim());
+        if (trimmed.some((value) => !value) || new Set(trimmed).size !== 1)
+            return fail("In --url: ?project= must name one project id or slug. Remove empty or conflicting values.", 2);
+        projectValue = trimmed[0];
+    }
+    let project;
+    let serverName = SERVER_NAME;
+    if (projectValue !== undefined) {
+        const selected = parseProject(projectValue);
+        if ("error" in selected)
+            return fail(`${parsed.values.project === undefined ? "In --url: " : ""}${selected.error}\n\n${MCP_USAGE}`, 2);
+        project = selected.project;
+        serverName = selected.serverName;
+    }
+    url = projectMcpUrl(url, project);
     // --toolsets wins over a selection already in --url, which wins over the client's default.
-    // Both sources are validated: Hue ignores an unknown name and would list every tool.
+    // Both sources are validated: Hue ignores an unknown name and would list its default.
     const requested = parsed.values.toolsets ?? new URL(url).searchParams.get("toolsets");
     let toolsets = DEFAULT_TOOLSETS[clientId];
     if (requested !== null) {
@@ -583,17 +652,13 @@ export async function runMcpCommand(argv, io = {}) {
             return fail(`${parsed.values.toolsets === undefined ? "In --url: " : ""}${selected.error}\n\n${MCP_USAGE}`, 2);
         toolsets = selected.toolsets;
     }
-    // `all` is Hue's default, so it needs no selection.
-    if (toolsets === "all")
-        toolsets = undefined;
-    if (auth === "key")
-        url = toolsetsMcpUrl(url, toolsets);
-    const plan = planFor(clientId, auth, scope, url, auth === "oauth" ? toolsets : undefined);
+    url = toolsetsMcpUrl(url, toolsets);
+    const plan = planFor(clientId, auth, scope, url, serverName);
     if (parsed.values.print) {
         stdout.write(plan.snippet);
         return 0;
     }
-    const steps = nextSteps(clientId, auth, toolsets);
+    const steps = nextSteps(clientId, auth, serverName, project);
     if (plan.kind === "manual") {
         out(plan.hint);
         stdout.write(plan.snippet);
@@ -619,7 +684,7 @@ export async function runMcpCommand(argv, io = {}) {
             out(`Running: ${command.display}`);
             const code = await runClientCli(executable, command.args, { cwd, env, stdout, stderr });
             if (code === 0) {
-                out(`Registered the "${SERVER_NAME}" MCP server (${url}) with ${command.label}.`);
+                out(`Registered the "${serverName}" MCP server (${url}) with ${command.label}.`);
                 continue;
             }
             failed = true;
@@ -636,7 +701,7 @@ export async function runMcpCommand(argv, io = {}) {
     let content;
     try {
         const existing = await readJsonConfig(path, display);
-        let merged = mergeServerEntry(existing, plan.key, plan.entry, display);
+        let merged = mergeServerEntry(existing, plan.key, plan.entry, display, serverName);
         if (plan.input)
             merged = mergeVscodeInput(merged, plan.input, display);
         content = json(merged);
@@ -657,7 +722,7 @@ export async function runMcpCommand(argv, io = {}) {
     catch (error) {
         return fail(`Could not write ${display}: ${error.message}`);
     }
-    out(`Wrote ${display} with the "${SERVER_NAME}" MCP server (${url}).`);
+    out(`Wrote ${display} with the "${serverName}" MCP server (${url}).`);
     for (const line of steps)
         out(line);
     return 0;

package/dist/evals/client.d.ts

@@ -44,7 +44,8 @@ export declare class EvaluationClient {
     private readonly timeoutMillis;
     constructor(options: EvaluationClientOptions);
     /** Sends one request to Hue, again after the wait while Hue refuses it with a short
-     * `Retry-After`. `init` runs for every attempt, so each has its own timeout. */
+     * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
+     * each attempt, and a wait to send one again, whose refusal is then the caller's error. */
     private send;
     private request;
     /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size.
@@ -170,8 +171,10 @@ export declare class EvaluationClient {
     revokeAttemptConnection(input: {
         bindingId: string;
     }): Promise<import("./attempt.js").RevokeAttemptResult>;
-    /** Reads one artifact reservation and its verification state. */
-    getArtifact(id: string): Promise<ArtifactReservation>;
+    /** Reads one artifact reservation and its verification state. `signal` ends the request. */
+    getArtifact(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactReservation>;
     /** Reserves an artifact by declared identity; replaying the key returns the same reservation. */
     reserveArtifact(input: {
         /** Stable key; replaying it returns the same reservation. */
@@ -187,8 +190,11 @@ export declare class EvaluationClient {
     }): Promise<ArtifactReservation>;
     /** Issues a short-lived storage capability for staging the reserved artifact's bytes. */
     requestArtifactUpload(id: string): Promise<ArtifactUpload>;
-    /** Asks Hue to verify the staged bytes against the declared identity. */
-    completeArtifact(id: string): Promise<ArtifactReservation>;
+    /** Asks Hue to verify the staged bytes against the declared identity. `signal` ends the
+     * request, and a wait to send it again. */
+    completeArtifact(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactReservation>;
     /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id: string, input: CompleteExecution): Promise<Completion>;
     /** Marks an experiment finished. */

package/dist/evals/client.js

@@ -149,12 +149,15 @@ export class EvaluationClient {
         this.timeoutMillis = validated.timeoutMillis;
     }
     /** Sends one request to Hue, again after the wait while Hue refuses it with a short
-     * `Retry-After`. `init` runs for every attempt, so each has its own timeout. */
-    async send(url, init) {
+     * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
+     * each attempt, and a wait to send one again, whose refusal is then the caller's error. */
+    async send(url, init, signal) {
         for (let attempt = 0;; attempt++) {
             let response;
             try {
-                response = await fetch(url, init());
+                const attemptInit = init();
+                const signals = [attemptInit.signal, signal].filter((item) => !!item);
+                response = await fetch(url, { ...attemptInit, signal: AbortSignal.any(signals) });
             }
             catch {
                 throw new HueApiError();
@@ -164,10 +167,23 @@ export class EvaluationClient {
                 return response;
             await response.body?.cancel().catch(() => undefined);
             // Never sooner than asked; the jitter spreads out parallel requests refused together.
-            await new Promise((resolve) => setTimeout(resolve, seconds * 1000 * (1 + Math.random() * 0.5)));
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", done);
+                    resolve();
+                };
+                const timer = setTimeout(done, seconds * 1000 * (1 + Math.random() * 0.5));
+                signal?.addEventListener("abort", done, { once: true });
+                // The signal may have ended while the refusal's body was cancelled.
+                if (signal?.aborted)
+                    done();
+            });
+            if (signal?.aborted)
+                throw new HueApiError(response.status, askedRetryAfter(response));
         }
     }
-    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }) {
+    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }, signal) {
         // Optional top-level fields are omitted intentionally; nested undefined remains invalid.
         const payload = body === undefined
             ? undefined
@@ -181,7 +197,7 @@ export class EvaluationClient {
             body: payload,
             redirect: "error",
             signal: AbortSignal.timeout(this.timeoutMillis),
-        }));
+        }), signal);
         if (!response.ok) {
             await response.body?.cancel();
             throw new HueApiError(response.status, askedRetryAfter(response));
@@ -503,9 +519,9 @@ export class EvaluationClient {
             throw new HueApiError();
         }
     }
-    /** Reads one artifact reservation and its verification state. */
-    getArtifact(id) {
-        return this.request("GET", `/artifacts/${uuid(id)}`);
+    /** Reads one artifact reservation and its verification state. `signal` ends the request. */
+    getArtifact(id, options = {}) {
+        return this.request("GET", `/artifacts/${uuid(id)}`, undefined, undefined, options.signal);
     }
     /** Reserves an artifact by declared identity; replaying the key returns the same reservation. */
     reserveArtifact(input) {
@@ -515,9 +531,10 @@ export class EvaluationClient {
     requestArtifactUpload(id) {
         return this.request("POST", `/artifacts/${uuid(id)}/upload`, {});
     }
-    /** Asks Hue to verify the staged bytes against the declared identity. */
-    completeArtifact(id) {
-        return this.request("POST", `/artifacts/${uuid(id)}/complete`, {});
+    /** Asks Hue to verify the staged bytes against the declared identity. `signal` ends the
+     * request, and a wait to send it again. */
+    completeArtifact(id, options = {}) {
+        return this.request("POST", `/artifacts/${uuid(id)}/complete`, {}, undefined, options.signal);
     }
     /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id, input) {

package/dist/evals/files.js

@@ -339,21 +339,33 @@ function mayStillVerify(error) {
  * a pause: ready is returned; verifying is completed again, which Hue refuses while its lease
  * holds and restarts once it lapsed; an artifact a retryable refusal (a lost response, 429 or 503)
  * left unverified is completed again up to three times; any other state is returned for the
- * caller to refuse (a resume uploads a rejected artifact again). All within `timing.settleMillis`.
+ * caller to refuse (a resume uploads a rejected artifact again). All within `timing.settleMillis`,
+ * which also ends a request in flight and the client's own wait to send one again.
  */
 async function settleArtifact(client, id, timing) {
     const deadline = Date.now() + timing.settleMillis;
+    const signal = AbortSignal.timeout(timing.settleMillis);
+    // The last state read, which names the state when the deadline cuts off a request at it.
+    let known;
+    const timedOut = (last) => {
+        const seconds = Math.round(timing.settleMillis / 1000);
+        return new Error(last?.state === "verifying"
+            ? `Hue was still verifying generated file ${id} after ${seconds} seconds`
+            : `Hue had not verified generated file ${id} after ${seconds} seconds (${last ? `it was ${last.state}` : "its state could not be read"})`);
+    };
     let pause = timing.pollMillis;
     let retries = 0;
     for (;;) {
         let refusedForNow;
         let asked = 0;
         try {
-            return (await client.completeArtifact(id)).state;
+            return (await client.completeArtifact(id, { signal })).state;
         }
         catch (error) {
-            if (!mayStillVerify(error) || Date.now() >= deadline)
+            if (!mayStillVerify(error))
                 throw error;
+            if (Date.now() >= deadline)
+                throw timedOut(known);
             refusedForNow = error.status !== 409;
             // A refusal that says how long to wait is waited out, within the settling window.
             asked = (error.retryAfterSeconds ?? 0) * 1000;
@@ -362,7 +374,7 @@ async function settleArtifact(client, id, timing) {
         pause = Math.min(pause * 2, timing.maxPollMillis);
         let current;
         try {
-            current = await client.getArtifact(id);
+            current = known = await client.getArtifact(id, { signal });
         }
         catch (error) {
             if (!mayStillVerify(error))
@@ -375,12 +387,8 @@ async function settleArtifact(client, id, timing) {
             current.failureCode !== "mismatch";
         if (current && current.state !== "verifying" && !(unverified && refusedForNow && retries++ < 3))
             return current.state;
-        if (Date.now() >= deadline) {
-            const seconds = Math.round(timing.settleMillis / 1000);
-            throw new Error(current?.state === "verifying"
-                ? `Hue was still verifying generated file ${id} after ${seconds} seconds`
-                : `Hue had not verified generated file ${id} after ${seconds} seconds (${current ? `it was ${current.state}` : "its state could not be read"})`);
-        }
+        if (Date.now() >= deadline)
+            throw timedOut(current ?? known);
     }
 }
 /**

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.11.0";
+export declare const sdkVersion = "0.11.2";

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.11.0";
+export const sdkVersion = "0.11.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "private": false,
   "license": "MIT",
   "publishConfig": {