@hue-run/sdk 0.11.3 → 0.12.0

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.3`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.12.0`, `@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. |
@@ -285,8 +299,9 @@ the same reason, and quote a URL with a query such as `?read_only=true`, whose `
 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.
 
@@ -454,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.3.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.12.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -465,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.3.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.12.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json

package/EVALUATIONS.md

@@ -116,7 +116,7 @@ Both choices are required and independent:
 
 Frozen dataset inputs/references already exist on Hue. Their presence is independent of these switches. No output is inferred from telemetry. JavaScript `undefined` means unavailable output; JSON `null`, false, zero and empty string remain present values. Historical subjects with unavailable output produce skipped results without executing a scorer callback. A failed quality metric remains `state:"scored"` with `passed:false`. Target errors and scorer errors remain separate. Target error types are generalized to `TargetError`; when content is enabled, bounded messages may be stored. Never put credentials in error messages, output, custom metric values, names or metadata.
 
-`traceEvidence:{mode:"required"}` waits for trace and log export acknowledgement after the root span ends. The explicit alternative `{mode:"omit",reason:"..."}` stores the omission reason and declared trace ID without a fake snapshot. It can complete despite an export failure; export diagnostics remain available on the Hue client. There is no automatic fallback to omission. When required telemetry is not accepted, the runner by default keeps the saved outcome, leaves the execution started and rejects (`traceNotAccepted: "stop"`). With `traceNotAccepted: "fail_case"` it instead completes that case as failed (a `TelemetryNotAccepted` error, the evidence omitted with a reason starting `telemetry_not_accepted`, and no output or generated files attached, so no scorer can pass it), calls `onTelemetryNotAccepted(entry)` once, as soon as it completes the case (a resumed call only lists it), lists it in `report.telemetryNotAccepted` with sanitized issue counts, and goes on; `hue eval` uses this. A scorer that grades only the world can still score such a case, so treat a listed case as failed whatever its results say, as `hue eval` does.
+`traceEvidence:{mode:"required"}` waits for trace and log export acknowledgement after the root span ends. The transport is shared by every case in flight, so each export issue names the traces of the records it concerned (`ExportIssue.traceIds`): a refused or rejected batch, a dropped record, a capture failure inside a case. A failure that names the case's trace is that case's own and final (its checkpoint reads `failed`, and resume refuses it); one that names only other traces leaves the case accepted; one that names no trace (a processor flush that failed) or a rejection in a batch of several traces is decided by the case's trace receipt, at once or on resume for a checkpoint still `pending`: the receipt must hold the case's root span and at least as many spans as the case ended (the checkpoint records the count at the flush; without it the receipt does not accept). The explicit alternative `{mode:"omit",reason:"..."}` stores the omission reason and declared trace ID without a fake snapshot. It can complete despite an export failure; export diagnostics remain available on the Hue client. There is no automatic fallback to omission. When required telemetry is not accepted, the runner by default keeps the saved outcome, leaves the execution started and rejects (`traceNotAccepted: "stop"`). With `traceNotAccepted: "fail_case"` it instead completes that case as failed (a `TelemetryNotAccepted` error, the evidence omitted with a reason starting `telemetry_not_accepted`, and no output or generated files attached, so no scorer can pass it), calls `onTelemetryNotAccepted(entry)` once, as soon as it completes the case (a resumed call only lists it), lists it in `report.telemetryNotAccepted` with sanitized issue counts, and goes on; `hue eval` uses this. A scorer that grades only the world can still score such a case, so treat a listed case as failed whatever its results say, as `hue eval` does.
 
 ## Local scorers
 
@@ -252,14 +252,30 @@ without invoking the target or scorers. A lost preparation acknowledgement remai
 and is never recovered through binding reads, credential refresh or target replay. Synthetic
 acceptance does not contact official Gmail or claim universal provider parity.
 
-Completion or result-upload failures keep the run claimed by the durable worker identity.
-Restart with the same checkpoint directory to resume saved uploads without invoking the
-candidate again. A lost world-seal acknowledgement is recovered by reading authoritative world
-state. If the seal or candidate outcome cannot be confirmed, or an outcome cannot be serialized,
-the worker reports `attention` and stops; operator investigation is required. Such runs are not
-automatically reclaimed, and presenting the same uncertain checkpoint again cannot replay the
-candidate. Public package acceptance proves this lifecycle against local fixtures; exact
-installed-registry-package to hosted-facade acceptance remains a post-publication Fern gate.
+The worker does not die with one failure. A read, or a mutation the server deduplicates by its
+idempotency key (the worker's own register, claim, heartbeat and completion included), is sent
+again after a connection failure, a timeout or a 408 or 5xx that carried no `Retry-After`, up to
+`maxAttempts` (default 4) times; a mutation without a key is sent once. A registration or claim
+that still fails transiently is reported through `onPollError` and polled again with a growing
+wait; a refusal Hue decided on (a revoked key, a disabled agent) is thrown. A transient failure
+of a completion or result upload keeps the run claimed by the durable worker identity: the next
+claim returns it to the same process, which resumes saved uploads without invoking the candidate
+again (`onRunFailed` says `retry`), and after `maxRunAttempts` (default 5) such failures the run
+is given up as `attention` for a project member to requeue or cancel from its run page; a failure
+that would recur (a refusal Hue decided on, a case file whose bytes differ from its manifest) is
+given up at once. A lost
+world-seal acknowledgement is recovered by reading authoritative world state. If the seal or
+candidate outcome cannot be confirmed, or an outcome cannot be serialized, the run is given up
+as `attention` at once and the worker goes on to other runs; when Hue cannot record that either,
+the worker stops with the error. Presenting the same uncertain checkpoint again cannot replay the
+candidate. `maxRuns` counts runs that settled either way. Inside a run, one case's own failure
+does not stop the cases beside it; a failure every case would share (Hue not answering or
+refusing, telemetry not accepted, a world that could not be sealed) stops new cases from
+starting until the run resumes. Each world's lifetime is `worldTtlSeconds` (the server's default
+is an hour): a target still running past it is told through `context.signal`, its case ends as
+an `error` of type `TargetTimeout` and the world is sealed abandoned. Public package acceptance
+proves this lifecycle against local fixtures; exact installed-registry-package to hosted-facade
+acceptance remains a post-publication Fern gate.
 
 ## Direct cases and files
 

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`

package/dist/cli/eval.js

@@ -8,7 +8,7 @@ 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, checkpointPath } from "../evals/checkpoint.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) => {
@@ -1300,6 +1302,20 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
         deprecationWarnings: false,
         signal,
         ...(maxRuns === undefined ? {} : { maxRuns }),
+        onPollError(error) {
+            output.error(`Hue did not answer the poll (${explain(error)}); polling again`);
+        },
+        onRunFailed(failure) {
+            const run = `Run ${failure.runId}`;
+            if (failure.outcome === "retry") {
+                const waitMillis = failure.waitMillis ?? 0;
+                output.error(`${run} attempt ${failure.attempt} failed (${explain(failure.error)}); resuming in ${Math.round(waitMillis / 1000)} s`);
+            }
+            else if (failure.outcome === "attention")
+                output.error(`${run} needs attention (${explain(failure.error)}); requeue or cancel it from its run page`);
+            else
+                output.error(`${run} was released or cancelled in Hue; its outcome here is not recorded`);
+        },
         target(inputs, tools, context) {
             output.log(`[${context.item.externalKey}] agent started`);
             return adapter(inputs, {
@@ -1313,7 +1329,9 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
                 ...(context.connectionBundle ? { connectionBundle: context.connectionBundle } : {}),
                 files: context.files,
                 outputDirectory: context.outputDirectory,
-                signal,
+                // The case's own signal: the worker stopping, or the world's deadline passing, both
+                // end a command that would otherwise keep running past its timed-out case.
+                signal: context.signal ?? signal,
             });
         },
         async onCompleted(report) {

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.