@hue-run/sdk 0.11.1 → 0.11.3

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.1`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.11.3`, `@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
 
@@ -193,16 +194,26 @@ for staging). Hue's Settings page does not show these snippets; this command kee
   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>` chooses the tools the connection lists: `all`, `observe` (the production
-reads: projects, traces, spans and their recorded content, sessions, trace checks, intents and
-documentation), or the groups `project`, `traces`, `evals`, `environments`, `intents` and `docs`,
-comma-separated. 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`,
+`--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
@@ -212,6 +223,14 @@ with write access), so nothing is out of reach. `--toolsets` replaces a selectio
 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**. |
@@ -234,19 +253,41 @@ 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
-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
-`${HUE_MCP_KEY}` reference reaches them literally; the printed commands use single quotes for the
-same reason, and quote a URL with a query such as `?read_only=true`, whose `?` is a zsh glob.
+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 through a temporary file and an atomic rename. A new file is
+owner-only (mode `0600`, narrowed further by the umask), because other servers' literal tokens often
+end up in it; a replaced file keeps its read, write and execute permissions, so a file kept at
+`0600` is never widened, except that other accounts lose write access (they could add a command for
+the client to run). It keeps its group, and its owner when root runs the command (if root cannot
+give the file back, the write fails and the old file stays); when the group cannot be kept, the
+group and other accounts get only the access both had. Setuid, setgid and sticky bits are dropped,
+and an access control list is not kept: the replacement has only the mode bits, whose group bits are
+the list's mask, plus any default list the directory gives new files, whose entries then get up to
+the group's access. Restore a list afterwards if you use one. A symlinked file, or a symlinked
+`.cursor` or `.vscode` directory, is refused; the current directory itself may be reached through a
+symlink. The directory is checked before the file is read and again before the rename, and a
+different file found in place of the one read is refused, but not atomically: an account that can
+write the project directory and races the command can still swap in a link between the last check
+and the rename. `--dry-run` prints the resulting file content or commands without writing or
+running. In printed file content, every header and `env` value, and each other credential it
+recognizes (a known token prefix, the value of an option such as `--api-key VALUE`, `-H VALUE`,
+`-e NAME=VALUE` or `--token=VALUE`, a field or assignment such as `clientSecret`, `key` or
+`STRIPE_KEY=`, a token-like URL path segment, a URL's query values, which read `%5Bredacted%5D`), is
+shown as `[redacted]` unless the whole value is a variable or input reference such as
+`Bearer ${HUE_MCP_KEY}`; the file keeps the values. Hue's own URL shows its `toolsets`, `project`
+and `read_only` selections, with every other query value and any token-like path segment as
+`[redacted]`, there and in the lines that report what the command did; a command printed for you to
+run keeps `--url` as given. `--print` prints only the snippet. Client CLIs run without a shell, so
+the `${HUE_MCP_KEY}` reference reaches them literally; the printed commands use single quotes for
+the same reason, and quote a URL with a query such as `?read_only=true`, whose `?` is a zsh glob.
 
 After a key installation the command reminds you to export `HUE_MCP_KEY` in the shell that starts
 the client (VS Code prompts for the key instead). A desktop app started from the Dock or a launcher
 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
@@ -255,12 +296,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
@@ -269,8 +308,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.
 
@@ -282,12 +321,14 @@ 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 waiting
+pull that forwarded something is not repeated until 50 ms after it began, and one 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`
@@ -298,15 +339,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
 
@@ -412,7 +454,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.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.11.3.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -423,7 +465,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.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.11.3.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json

package/README.md

@@ -165,8 +165,10 @@ call carries `error.type` (`mcp_error`, the provider's status or error code) and
 text, credentials scrubbed (URL userinfo, query values and fragments, or the whole URL for a scheme
 other than `http(s)`, `ws(s)` and `ftp`; tokens with a known credential prefix such as `hue_sk_`,
 `sk-` or `xoxb-`; authorization-scheme credentials and an `Authorization` header's whole value;
-the value of a credential-named `key=value` or `key: value` pair, quoted or not) and cut to 1,024
-characters. An `mcp_list_tools`
+the value of a credential-named `key=value`, `key: value` or `key => value` pair, quoted, bare or
+a whole `[…]` or `{…}` (to the end of the text when it does not close), a quote that does not close
+on its line running to its end; a JSON or `%` escape such as `\n` or `%20` ends a word) and cut to
+1,024 characters and a `…`. An `mcp_list_tools`
 item becomes a `tools/list` child span with that server's `gen_ai.tool.definitions`; with
 `captureContent: false` it carries only `hue.tool.names` and `hue.tool.definitions.sha256`, the
 summary described below. Pass the request so each server's host is recorded as `server.address`

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

@@ -11,7 +11,7 @@ import { createEnvironmentClient } from "../environment/client.js";
 import { agentEnvironment, isHueControlPlaneCredential, stripHueControlPlaneCredentials, writeMcpConfig, } from "../environment/world.js";
 import { EvaluationClient, HueApiError } from "../evals/client.js";
 import { TargetResult } from "../evals/types.js";
-import { CheckpointIdentityError, CheckpointStore } from "../evals/checkpoint.js";
+import { CheckpointIdentityError, CheckpointStore, checkpointPath } from "../evals/checkpoint.js";
 import { onForcedExit, runForcedExitCleanups } from "../evals/exit-cleanup.js";
 import { safeFilename } from "../evals/files.js";
 import { digest } from "../evals/json.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) {
@@ -809,9 +810,13 @@ export function explain(error) {
 }
 /** `.hue/eval/<agent-key>/<project>/<leaf>` unless overridden; the SDK binds each store to one
  * project and origin, so switching keys or deployments must not collide. */
-async function prepareCheckpointDirectory(explicit, agentKey, projectId, leaf) {
+async function prepareCheckpointDirectory(explicit, agentKey, projectId, ...leaf) {
+    const segments = [
+        [projectId, "project id"],
+        ...leaf.map((part) => [part, "checkpoint kind"]),
+    ];
     if (explicit)
-        return join(resolve(explicit), projectId, leaf);
+        return checkpointPath(explicit, ...segments);
     const root = resolve(".hue", "eval");
     await mkdir(root, { recursive: true, mode: 0o700 });
     const ignore = join(root, ".gitignore");
@@ -821,7 +826,7 @@ async function prepareCheckpointDirectory(explicit, agentKey, projectId, leaf) {
     catch {
         await writeFile(ignore, "*\n", { flag: "wx", mode: 0o600 }).catch(() => undefined);
     }
-    return join(root, agentKey, projectId, leaf);
+    return checkpointPath(join(root, agentKey), ...segments);
 }
 /** Worker-side client that reports registration and claims without changing the worker. */
 class ObservedClient extends EvaluationClient {
@@ -1209,7 +1214,7 @@ async function runDirect(run, connection) {
             client,
             hue: run.hue,
             experimentId,
-            checkpointDirectory: join(store.directory, experimentId),
+            checkpointDirectory: checkpointPath(store.directory, [experimentId, "experiment id"]),
             // Outputs, error messages and explanations are stored unless opted out; --content governs
             // only the telemetry.
             persistResultContent: !values["no-output"],
@@ -1267,7 +1272,7 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
         ? 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, join("worker", slug(agent.revision) || "dev"));
+    const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, "worker", slug(agent.revision) || "dev");
     let current;
     client.onRegistered = (registered) => {
         output.log(`Registered agent ${registered.key} (revision ${registered.revision}) with ${connection.baseUrl}; waiting for runs launched from Hue${maxRuns ? ` (stops after ${maxRuns})` : " (Ctrl+C to stop)"}`);

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,17 @@ 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;
+/** The least time between the starts of pulls that forwarded something, so a Hue that answers
+ * every pull at once with new deliveries is pulled at most 20 times a second. */
+const BUSY_PULL_FLOOR_MS = 50;
+/** The most of a text from elsewhere (an error message, a URL) that is scrubbed and printed, in
+ * code points, as of a provider's error text; a longer one is cut there and `…` marks the cut. */
+const MAX_FOREIGN_TEXT = 16_384;
+/** 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 +76,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 +425,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))
@@ -485,7 +497,16 @@ export async function runListenCommand(argv, io = {}) {
             out = out.replaceAll(secret, "[redacted]");
         return out.replace(/[^\P{Cc}\n\t]|\p{Cf}/gu, " ");
     };
-    const foreign = (text) => scrubCredentialText(text);
+    const foreign = (text) => {
+        let kept = "";
+        let seen = 0;
+        for (const character of text) {
+            if (seen++ === MAX_FOREIGN_TEXT)
+                return `${scrubCredentialText(kept, true)}…`;
+            kept += character;
+        }
+        return scrubCredentialText(text);
+    };
     const out = (line) => void stdout.write(`${clean(line)}\n`);
     const warn = (line) => void stderr.write(`${clean(line)}\n`);
     let subscription;
@@ -547,16 +568,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 +759,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 +775,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 +786,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 +811,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 +820,30 @@ 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.
+            // One that forwarded something is repeated no sooner than BUSY_PULL_FLOOR_MS after it began.
+            const elapsed = performance.now() - pulledAt;
+            if (waited && !forwarded.includes(true) && elapsed < IDLE_PULL_FLOOR_MS)
+                await sleep(IDLE_PULL_FLOOR_MS, stopping.signal);
+            else if (waited && elapsed < BUSY_PULL_FLOOR_MS)
+                await sleep(BUSY_PULL_FLOOR_MS - elapsed, 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

@@ -20,15 +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"];
+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                  Tools to list, comma-separated: all, observe (production reads),\n                  project, traces, evals, environments, intents or docs, added to the\n                  URL as ?toolsets=. 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.";
+/** 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.
@@ -38,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;
@@ -92,9 +94,9 @@ export declare function renderMcpSnippets(url: string): {
 /**
  * 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=` selects tools here as it does for a key.
+ * so `?toolsets=` and `?project=` select tools and a project here as they do for a key.
  */
-export declare function renderMcpSignInSnippets(url: string): {
+export declare function renderMcpSignInSnippets(url: string, serverName?: string): {
     claudeCodeServer: {
         type: string;
         url: string;
@@ -124,6 +126,15 @@ export declare function parseToolsets(value: string): {
  * 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. */