@hue-run/sdk 0.11.2 → 0.11.4

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.2`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.11.4`, `@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.
 
@@ -141,7 +141,7 @@ uses the observed predecessor for compare-and-swap. A conflict refreshes status
 At most 32 distinct handoff IDs exist per installation; `SETUP_HANDOFF_LIMIT` is terminal. Replacing a
 handoff does not create a trial, reset quota or rerun business work.
 
-## Sign in and store keys
+## Store project keys
 
 `hue login` stores keys that a person creates in Hue; it never mints one, because setup
 credentials are deliberately isolated from ordinary project keys. It prints the key settings page
@@ -185,14 +185,27 @@ for staging). Hue's Settings page does not show these snippets; this command kee
 
 `--auth` chooses how the client authenticates:
 
-- `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 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.
+  write** access to every active project in the organization the consent page names, within your
+  role, so an agent first calls `list_projects` and passes the chosen project's id as `project_id`.
+  The approval lasts 30 days; then sign in again. Sign-in covers the MCP server only: tracing and
+  `hue eval` still use a project key as `HUE_API_KEY`. It is available for `claude-code`, `codex`
+  and `conductor`. Hue does not yet accept Cursor's sign-in callback, so `cursor` and the other
+  clients use a key.
+- `key` references the `HUE_MCP_KEY` environment variable, which `hue login` stores in
+  `.env.hue`. A key value is never written. Use a key for read-only access (a **Read** key, which
+  only `hue login --keys coding-agent` accepts), for a run that cannot complete a browser sign-in
+  (CI, `claude -p`), or for access that must outlast 30 days.
+
+Without `--auth`, `claude-code`, `codex` and `conductor` sign in and the other clients use a key.
+`--read-only` (or `read_only=true` in `--url`) selects a key. Otherwise `claude-code` and `codex`
+keep the choice of the server's existing entry, in `./.mcp.json` or as `codex mcp get` reports it,
+so a rerun that changes `--toolsets` keeps a key and its `read_only`; for a new entry they use a
+key when `HUE_MCP_KEY` is set (only its presence is checked). When `codex` is on `PATH` but `codex mcp get` fails
+for another reason, the command asks for `--auth` rather than guess which to keep. `conductor` keeps signing in, since
+its agents read the login-shell environment Conductor captures rather than your terminal's. The
+command names its choice on stderr; pass `--auth` to replace an entry as given.
 
 `--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
@@ -203,10 +216,11 @@ The printed sign-in Codex TOML keeps its URL bare and sends `X-Hue-MCP-Project`
 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
+`--read-only` selects a key and adds `?read_only=true` to its 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.
+With `--auth oauth` it is refused, as is any `read_only` in a sign-in `--url` (Hue reads only
+`true` or `1`): 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`; the profiles `observe`
 (production reads), `author` (author evaluations) and `evaluate` (run an agent against a case);
@@ -233,9 +247,9 @@ reviewed cases `case_id`, environment versions `environment_version_id`, and tra
 
 | 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. 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`). |
+| `claude-code` | Merges `mcpServers.hue` into `./.mcp.json`. `--scope user` runs `claude mcp add --transport http --scope user hue URL --header 'Authorization: Bearer ${HUE_MCP_KEY}'` when `claude` is on `PATH`, otherwise prints it. | Merges `mcpServers.hue` with only `type` and `url` into `./.mcp.json`; `--scope user` runs `claude mcp add --transport http --scope user hue URL`. Then restart Claude Code, run `/mcp`, select `hue` and choose **Authenticate**. |
+| `codex` | Runs `codex mcp add hue --url URL --bearer-token-env-var HUE_MCP_KEY`, or prints the `[mcp_servers.hue]` TOML block for `~/.codex/config.toml`. | Runs `codex mcp add hue --url URL`, which signs in at once and waits up to 5 minutes for the browser; without `--auth` and outside a terminal (CI, an agent's shell tool) the command prints it instead. A sign-in that does not finish leaves the server registered, and `codex mcp login hue` signs in. Then start a new Codex session. The printed TOML block keeps its URL bare and sends the selection as the `X-Hue-MCP-Toolsets` header. |
+| `conductor` | Runs the Claude Code user-scope and Codex key commands above. | Runs `claude mcp add --transport http --scope user hue URL` and `codex mcp add hue --url URL` (printed outside a terminal, as for `codex`). Then use `hue`'s authentication action in Conductor's MCP status (the plug icon or `/mcp-status`). |
 | `cursor` | Merges `mcpServers.hue` into `./.cursor/mcp.json` with `${env:HUE_MCP_KEY}`. | Refused. |
 | `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. |
@@ -255,17 +269,39 @@ again with `--auth key`.
 JSON files are parsed and merged: other servers, inputs and top-level fields are kept, only the
 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
-`${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.
+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:
+Conductor captures, so sign-in is the simpler choice there. After a sign-in installation it says
+how the client loads the server (restart Claude Code, or a new Codex session) and names its
+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 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.
 
@@ -300,8 +336,9 @@ 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 pull
-that answers at once with nothing new to forward is not repeated for a second. A provider retry of
+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
@@ -432,7 +469,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.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.11.4.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -443,7 +480,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.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.11.4.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json

package/README.md

@@ -82,11 +82,12 @@ account linkage; the original request evidence is retained and business work is
 claim. Setup never enables content capture or creates a simulation, Hue Run, evaluation, source capture
 or remote execution. See the [setup CLI contract](./CLI.md) for the supported shapes and release gates.
 
-For an existing account, `hue login` validates keys created in Hue Settings and stores them in
-`.env.hue` without printing them, and `hue mcp install --client claude-code` (or `codex`,
-`conductor`, `cursor`, `vscode`, `windsurf`, `gemini`) writes the Hue MCP configuration that
-references `HUE_MCP_KEY`, or with `--auth oauth` only the URL, for signing in with Hue. See
-[Sign in and store keys](./CLI.md#sign-in-and-store-keys) and
+For an existing account, `hue mcp install --client claude-code` (or `codex`, `conductor`,
+`cursor`, `vscode`, `windsurf`, `gemini`) writes the Hue MCP configuration. For Claude Code, Codex
+and Conductor it holds only the URL, and you sign in with Hue in the client; for the other clients,
+`--read-only` and `--auth key` it references `HUE_MCP_KEY` (VS Code prompts for the key).
+`hue login` validates keys created in Hue Settings and stores them in `.env.hue` without printing
+them. See [Store project keys](./CLI.md#store-project-keys) and
 [Install the MCP for your coding agent](./CLI.md#install-the-mcp-for-your-coding-agent).
 
 `checkConnection()` rejects with `HueConnectionError`: its fixed message is safe to log, `status`
@@ -165,8 +166,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.js

@@ -8,10 +8,10 @@ import { parseArgs } from "node:util";
 import { randomUUID } from "node:crypto";
 import { createHue } from "../client.js";
 import { createEnvironmentClient } from "../environment/client.js";
-import { agentEnvironment, isHueControlPlaneCredential, stripHueControlPlaneCredentials, writeMcpConfig, } from "../environment/world.js";
+import { agentEnvironment, isHueControlPlaneCredential, stripHueControlPlaneCredentials, withoutWorldVariables, 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";
@@ -583,11 +583,13 @@ function redacting(adapter) {
     };
 }
 /** The parent environment an agent child starts from: without Hue control-plane credentials
- * unless `--allow-hue-credentials` was passed. */
+ * unless `--allow-hue-credentials` was passed, and without any world variable. */
 function parentEnvironment(allowHueCredentials) {
-    return allowHueCredentials
+    // A world variable left in this process's environment belongs to another world: only the
+    // current case's world sets them, whether or not the case has one.
+    return withoutWorldVariables(allowHueCredentials
         ? Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined))
-        : stripHueControlPlaneCredentials(process.env);
+        : stripHueControlPlaneCredentials(process.env));
 }
 function commandAdapter(command, timeoutSeconds, options) {
     return async (inputs, context) => {
@@ -810,9 +812,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");
@@ -822,7 +828,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 {
@@ -1210,7 +1216,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"],
@@ -1268,7 +1274,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.js

@@ -35,6 +35,12 @@ const MAX_RETRY_AFTER_MS = 60_000;
 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;
@@ -491,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;
@@ -809,8 +824,12 @@ export async function runListenCommand(argv, io = {}) {
             // 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)
+            // 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 {

package/dist/cli/login.js

@@ -742,7 +742,8 @@ export async function runLoginCommand(argv, io = {}) {
     out("Next steps:");
     if (stored.includes("coding-agent"))
         // `hue mcp install` defaults to production; a non-default origin needs its own endpoint.
-        out(`  hue mcp install --client claude-code${mcpUrl === mcpUrlForOrigin(DEFAULT_ORIGIN) ? "" : ` --url ${mcpUrl}`}`);
+        // Without --auth it configures sign-in unless HUE_MCP_KEY is exported, so name the key stored.
+        out(`  hue mcp install --client claude-code --auth key${mcpUrl === mcpUrlForOrigin(DEFAULT_ORIGIN) ? "" : ` --url ${mcpUrl}`}`);
     if (stored.includes("evaluations"))
         out(`  hue eval --case "<name>" ./hue-agent.ts --env-file ${envDisplay}`);
     return 0;

package/dist/cli/mcp.d.ts

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