@hue-run/sdk 0.11.3 → 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.3`, `@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. |
@@ -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.11.4.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.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`

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) => {

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.

package/dist/cli/mcp.js

@@ -82,18 +82,21 @@ export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|codex|con
                        [--toolsets NAMES] [--url URL]
                        [--scope project|user] [--dry-run] [--print]
 
-Configure a coding agent to use the Hue MCP server. A key configuration references the
-${ENV_VAR} environment variable; a key value is never written. A sign-in configuration holds
-only the URL: the client opens Hue in a browser, where you approve access to the projects of
-one organization.
+Configure a coding agent to use the Hue MCP server. A sign-in configuration holds only the
+URL: the client opens Hue in a browser, where you approve access to the projects of one
+organization. A key configuration references the ${ENV_VAR} environment variable; a key value
+is never written.
 
 Options:
   --client NAME   Coding agent to configure (required)
-  --auth MODE     key: reference ${ENV_VAR} (the default, except for conductor)
-                  oauth: URL only, sign in with Hue in the client (claude-code, codex and
-                  conductor; the default for conductor)
-  --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A
-                  sign-in connection has Read and write access; use a Read key for read-only
+  --auth MODE     oauth: URL only, sign in with Hue in the client (claude-code, codex and
+                  conductor; their default)
+                  key: reference ${ENV_VAR} (the default for the other clients and with
+                  --read-only). Without --auth, claude-code and codex keep the choice of
+                  an existing entry, and use a key for a new one when ${ENV_VAR} is set
+  --read-only     Add ?read_only=true to a key configuration's URL so write tools are
+                  hidden; selects a key without --auth. A sign-in connection has Read and
+                  write access; use a Read key for read-only
   --project VALUE Pin the connection to one project by id or slug. Its tools omit project_id,
                   and the server is named hue-<value> so it can coexist with an unpinned hue
   --toolsets NAMES
@@ -114,7 +117,9 @@ Options:
 Files: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the
 current directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the
 snippet for its user configuration file. conductor registers the server for its Claude Code
-(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.`;
+(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.
+codex mcp add signs in at once and waits up to 5 minutes for the browser, so without --auth
+and outside a terminal the command prints it instead of running it.`;
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
 /**
  * A URL as a POSIX shell word for printed commands: `?` is a zsh glob and `&` ends a command, so a
@@ -281,6 +286,10 @@ export function readOnlyMcpUrl(url) {
     parsed.searchParams.set("read_only", "true");
     return parsed.href;
 }
+/** Whether Hue treats the URL as read-only: it honors only `read_only=true` or `read_only=1`. */
+function isReadOnlyUrl(url) {
+    return ["true", "1"].includes(new URL(url).searchParams.get("read_only") ?? "");
+}
 class ConfigError extends Error {
     constructor(message) {
         super(message);
@@ -501,9 +510,9 @@ function redactUrlPath(value) {
 const PARAMETER_NAME = /^[A-Za-z_][\w.-]{0,31}$/u;
 /**
  * The URL this command writes, as its output shows it: the selections it validated (`toolsets`,
- * `project`, and `read_only` when true or false) are kept; any other query value, and a token-like
- * path segment, becomes `[redacted]`. `parseMcpUrl` has already refused userinfo and a fragment.
- * Commands printed for a person to run keep the URL as given.
+ * `project`, and `read_only` when true, false, 1 or 0) are kept; any other query value, and a
+ * token-like path segment, becomes `[redacted]`. `parseMcpUrl` has already refused userinfo and a
+ * fragment. Commands printed for a person to run keep the URL as given.
  */
 function displayMcpUrl(url) {
     const parsed = new URL(url);
@@ -515,7 +524,7 @@ function displayMcpUrl(url) {
         const [name = "", value = ""] = pair.split("=", 2);
         const selection = name === "toolsets" ||
             name === "project" ||
-            (name === "read_only" && /^(?:true|false)$/u.test(value));
+            (name === "read_only" && /^(?:true|false|1|0)$/u.test(value));
         if (selection)
             return pair;
         return PARAMETER_NAME.test(name) &&
@@ -573,6 +582,8 @@ function redactConfig(root, serversKey, url, shownUrl) {
     };
     return redact(root, false, 0, false);
 }
+/** Whether a person is likely watching: login.ts opens a browser on the same test. */
+const isTerminal = (stream) => stream.isTTY === true;
 async function findExecutable(name, env) {
     const searchPath = env.PATH ?? env.Path ?? "";
     const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
@@ -618,6 +629,102 @@ function runClientCli(executable, args, options) {
         }
     });
 }
+/**
+ * A client CLI's exit code and output within ten seconds, none of it shown; null when it could not
+ * start or ran out of time.
+ */
+function readClientCli(executable, args, options) {
+    return new Promise((resolveRun) => {
+        try {
+            const child = spawn(executable, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+            const collect = () => {
+                const chunks = [];
+                let size = 0;
+                return {
+                    add: (chunk) => {
+                        size += chunk.length;
+                        if (size <= MAX_CONFIG_BYTES)
+                            chunks.push(chunk);
+                    },
+                    text: () => (size <= MAX_CONFIG_BYTES ? Buffer.concat(chunks).toString() : null),
+                };
+            };
+            const out = collect();
+            const err = collect();
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill();
+            }, 10_000);
+            child.stdout.on("data", out.add);
+            child.stderr.on("data", err.add);
+            child.once("error", () => {
+                clearTimeout(timer);
+                resolveRun(null);
+            });
+            child.once("close", (code) => {
+                clearTimeout(timer);
+                const stdout = out.text();
+                const stderr = err.text();
+                resolveRun(timedOut || code === null || stdout === null || stderr === null
+                    ? null
+                    : { code, stdout, stderr });
+            });
+        }
+        catch {
+            resolveRun(null);
+        }
+    });
+}
+const hasAuthorization = (headers) => isRecord(headers) && Object.keys(headers).some((name) => name.toLowerCase() === "authorization");
+/** The server's HTTP entry in `./.mcp.json`; an unreadable file is reported by the write. */
+async function readClaudeProjectEntry(cwd, serverName) {
+    let config;
+    try {
+        ({ config } = await readJsonConfig(resolve(cwd, ".mcp.json"), ".mcp.json"));
+    }
+    catch {
+        return undefined;
+    }
+    const servers = isRecord(config) ? config.mcpServers : undefined;
+    const entry = isRecord(servers) ? servers[serverName] : undefined;
+    if (!isRecord(entry) || typeof entry.url !== "string" || !parseMcpUrl(entry.url))
+        return undefined;
+    const auth = hasAuthorization(entry.headers) ? "key" : "oauth";
+    return { url: entry.url, auth, source: ".mcp.json" };
+}
+/**
+ * The server's entry in Codex's configuration, as `codex mcp get --json` reports it: `found` with
+ * its exact output, `none` when Codex says it has no such server (or holds one that is not an HTTP
+ * Hue entry), or `unknown` when Codex could not be asked or answered otherwise, which is never
+ * taken for `none`.
+ */
+async function readCodexEntry(executable, serverName, options) {
+    const result = await readClientCli(executable, ["mcp", "get", serverName, "--json"], options);
+    if (!result)
+        return { state: "unknown" };
+    if (result.code !== 0)
+        return result.stderr.includes(`No MCP server named '${serverName}' found`)
+            ? { state: "none" }
+            : { state: "unknown" };
+    let transport;
+    try {
+        transport = JSON.parse(result.stdout).transport;
+    }
+    catch {
+        return { state: "unknown" };
+    }
+    if (!isRecord(transport) || typeof transport.url !== "string" || !parseMcpUrl(transport.url))
+        return { state: "none" };
+    const key = Boolean(transport.bearer_token_env_var) ||
+        hasAuthorization(transport.http_headers) ||
+        hasAuthorization(transport.env_http_headers);
+    return {
+        state: "found",
+        entry: { url: transport.url, auth: key ? "key" : "oauth", source: "Codex's configuration" },
+        raw: result.stdout,
+    };
+}
 /** Validates the MCP endpoint: HTTPS, or HTTP for loopback test servers; no credentials or hash. */
 export function parseMcpUrl(value) {
     let url;
@@ -732,20 +839,69 @@ function planFor(client, auth, scope, url, serverName) {
         }
     }
 }
-function nextSteps(client, auth, serverName, project) {
+/**
+ * The authentication used without `--auth`, and the line saying why. A client that can sign in
+ * does, unless a key is asked for: read-only access (`--read-only`, or `read_only=true` in
+ * `--url`), which a sign-in connection does not have. For Claude Code and Codex, an existing entry
+ * keeps its choice, so rerunning the command, to change `--toolsets` for instance, never swaps a
+ * working setup; a key keeps its `read_only`. A new entry uses a key when `HUE_MCP_KEY` is set in
+ * `env`; only the variable's presence is checked. Conductor signed in by default before and keeps
+ * doing so: its agents read the login-shell environment Conductor captures, not this shell's. The
+ * other clients only take a key, so they get no line.
+ */
+function defaultAuth(client, readOnly, existing, env) {
+    if (!OAUTH_CLIENTS.includes(client))
+        return { auth: "key" };
+    if (readOnly)
+        return {
+            auth: "key",
+            note: `Using a key: ${readOnly} needs one, since a sign-in connection has Read and write access.`,
+        };
+    if (existing?.auth === "key") {
+        const keepReadOnly = isReadOnlyUrl(existing.url);
+        return {
+            auth: "key",
+            keepReadOnly,
+            note: keepReadOnly
+                ? `Keeping a read-only key, as the existing entry in ${existing.source} has; pass --auth key to drop read_only, or --auth oauth to sign in with Hue instead.`
+                : `Keeping a key, as the existing entry in ${existing.source} has; pass --auth oauth to sign in with Hue instead.`,
+        };
+    }
+    if (existing)
+        return {
+            auth: "oauth",
+            note: `Keeping sign-in with Hue, as the existing entry in ${existing.source} has; pass --auth key to use a key instead.`,
+        };
+    if (client !== "conductor" && env[ENV_VAR])
+        return {
+            auth: "key",
+            note: `Using a key (${ENV_VAR} is set); pass --auth oauth to sign in with Hue instead.`,
+        };
+    return {
+        auth: "oauth",
+        note: `Using sign-in with Hue (${client === "conductor" ? "Conductor's default" : `${ENV_VAR} is not set`}); pass --auth key to use a key instead.`,
+    };
+}
+function nextSteps(client, auth, serverName, project, scope, readOnly) {
     const label = CLIENT_LABELS[client];
     const approve = project
         ? `Sign in to Hue and approve the connection. It acts only on the pinned project ${project}, within your role; for read-only access, use a Read project key with --auth key.`
-        : "Sign in to Hue and approve the connection. It can read and write every active project in the organization you choose, within your role; for read-only access, use a Read project key with --auth key.";
+        : "Sign in to Hue and approve the connection. It can read and write every active project in the organization the consent page names, within your role; for read-only access, use a Read project key with --auth key.";
+    // A read-only configuration needs a key: plain hue login refuses a Read key.
+    const stored = readOnly
+        ? "hue login --keys coding-agent stores it in .env.hue and accepts a Read key"
+        : "hue login stores it in .env.hue";
     let lines;
     if (auth === "oauth")
         lines =
             client === "claude-code"
-                ? [`In Claude Code, run /mcp, select ${serverName} and choose Authenticate. ${approve}`]
+                ? [
+                    `Restart Claude Code (for example claude --continue)${scope === "project" ? ` and approve ${serverName} from .mcp.json` : ""}, then run /mcp, select ${serverName} and choose Authenticate. ${approve}`,
+                ]
                 : client === "codex"
                     ? [
                         `If Codex did not open Hue in your browser, run: codex mcp login ${serverName}`,
-                        approve,
+                        `${approve} Then start a new Codex session, which loads ${serverName}.`,
                     ]
                     : [
                         `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${serverName}'s authentication action. ${approve}`,
@@ -757,13 +913,13 @@ function nextSteps(client, auth, serverName, project) {
         ];
     else if (client === "conductor")
         lines = [
-            `Conductor agents read ${ENV_VAR} from the login-shell environment Conductor captures, so export it there, not only in a terminal; hue login stores it in .env.hue. Sign-in (--auth oauth) needs no variable.`,
+            `Conductor agents read ${ENV_VAR} from the login-shell environment Conductor captures, so export it there, not only in a terminal; ${stored}.${readOnly ? "" : " Sign-in (--auth oauth) needs no variable."}`,
         ];
     else
         lines = [
-            `Export ${ENV_VAR} in the shell that starts ${label}; hue login stores it in .env.hue:`,
+            `Export ${ENV_VAR} in the shell that starts ${label}; ${stored}:`,
             "  set -a; . ./.env.hue; set +a",
-            `An app started from the Dock or a launcher does not see that shell's variables; start ${label} from the shell${OAUTH_CLIENTS.includes(client) ? ", or sign in instead with --auth oauth" : ""}.`,
+            `An app started from the Dock or a launcher does not see that shell's variables; start ${label} from the shell${OAUTH_CLIENTS.includes(client) && !readOnly ? ", or sign in instead with --auth oauth" : ""}.`,
         ];
     // `codex mcp add` has no option for it, so a registered server gets the line by hand.
     if (client === "codex" || client === "conductor")
@@ -809,10 +965,10 @@ export async function runMcpCommand(argv, io = {}) {
     if (!client || !CLIENT_IDS.includes(client))
         return fail(`${client ? `Unknown client: ${client}.` : "--client is required."} Choose one of ${CLIENT_IDS.join(", ")}.\n\n${MCP_USAGE}`, 2);
     const clientId = client;
-    const auth = parsed.values.auth ?? (clientId === "conductor" ? "oauth" : "key");
-    if (auth !== "key" && auth !== "oauth")
+    const explicitAuth = parsed.values.auth;
+    if (explicitAuth !== undefined && explicitAuth !== "key" && explicitAuth !== "oauth")
         return fail(`--auth must be key or oauth.\n\n${MCP_USAGE}`, 2);
-    if (auth === "oauth" && !OAUTH_CLIENTS.includes(clientId))
+    if (explicitAuth === "oauth" && !OAUTH_CLIENTS.includes(clientId))
         return fail(clientId === "cursor"
             ? "--auth oauth is not available for cursor: Hue does not yet accept Cursor's sign-in callback. Use a key (the default), or sign in from claude-code or codex."
             : `--auth oauth is available for ${OAUTH_CLIENTS.join(", ")}. Use a key (the default) for ${clientId}.`, 2);
@@ -824,12 +980,6 @@ export async function runMcpCommand(argv, io = {}) {
     let url = parseMcpUrl(parsed.values.url ?? DEFAULT_MCP_URL);
     if (!url)
         return fail("--url must be an HTTPS URL such as https://mcp.hue.run/mcp (plain HTTP is accepted for loopback test servers only).", 2);
-    // A sign-in connection's access is chosen when it is approved; read_only is not part of it.
-    if (auth === "oauth" &&
-        (parsed.values["read-only"] || new URL(url).searchParams.has("read_only")))
-        return fail("A sign-in connection has Read and write access and cannot be made read-only by its URL. For read-only access, use a Read project key (--auth key), or add --read-only to a key configuration.", 2);
-    if (parsed.values["read-only"])
-        url = readOnlyMcpUrl(url);
     // --project replaces a pin already in --url. Without it, validate and keep the URL's pin.
     const urlProjects = new URL(url).searchParams.getAll("project");
     let projectValue = parsed.values.project;
@@ -848,6 +998,40 @@ export async function runMcpCommand(argv, io = {}) {
         project = selected.project;
         serverName = selected.serverName;
     }
+    const urlReadOnly = new URL(url).searchParams.has("read_only");
+    const readOnly = parsed.values["read-only"]
+        ? "--read-only"
+        : isReadOnlyUrl(url)
+            ? "read_only in --url"
+            : undefined;
+    // Without --auth or read_only, an existing entry keeps its choice. A user-scope `claude mcp add`
+    // refuses a name it already has, and Conductor keeps its default, so only these two are read.
+    let existing;
+    if (explicitAuth === undefined && !parsed.values["read-only"] && !urlReadOnly) {
+        if (clientId === "claude-code" && scope === "project")
+            existing = await readClaudeProjectEntry(cwd, serverName);
+        else if (clientId === "codex") {
+            // Without codex on PATH nothing is run, so nothing Codex holds is replaced. With it, an
+            // entry that cannot be read may hold either a key or a sign-in, so the command does not
+            // guess which to keep.
+            const codex = await findExecutable("codex", env);
+            const lookup = codex ? await readCodexEntry(codex, serverName, { cwd, env }) : undefined;
+            if (lookup?.state === "unknown")
+                return fail(`Could not read Codex's "${serverName}" entry (codex mcp get failed), so the command will not guess whether to keep a key or sign-in. Pass --auth oauth or --auth key.`, 2);
+            if (lookup?.state === "found")
+                existing = lookup.entry;
+        }
+    }
+    const { auth, keepReadOnly, note } = explicitAuth === undefined
+        ? defaultAuth(clientId, readOnly, existing, env)
+        : { auth: explicitAuth };
+    // A sign-in connection's access is chosen when it is approved; read_only is not part of it.
+    if (auth === "oauth" && readOnly)
+        return fail("A sign-in connection has Read and write access and cannot be made read-only by its URL. For read-only access, use a Read project key (--auth key), or add --read-only to a key configuration.", 2);
+    if (auth === "oauth" && urlReadOnly)
+        return fail("Remove read_only from --url: a sign-in URL does not carry it, since a sign-in connection has Read and write access, and Hue reads only read_only=true or 1. For read-only access, use a Read project key (--auth key).", 2);
+    if (parsed.values["read-only"] || keepReadOnly)
+        url = readOnlyMcpUrl(url);
     url = projectMcpUrl(url, project);
     // --toolsets wins over a selection already in --url, which wins over the client's default.
     // Both sources are validated: Hue ignores an unknown name and would list its default.
@@ -860,6 +1044,9 @@ export async function runMcpCommand(argv, io = {}) {
         toolsets = selected.toolsets;
     }
     url = toolsetsMcpUrl(url, toolsets);
+    // On stderr, so --print and --dry-run output stays as it was.
+    if (note)
+        stderr.write(`${note}\n`);
     const shownUrl = displayMcpUrl(url);
     // What the command reports doing; a command a person is to run is printed as given.
     const shownCommand = (command) => command.display.replaceAll(shellWord(url), () => shellWord(shownUrl));
@@ -868,7 +1055,7 @@ export async function runMcpCommand(argv, io = {}) {
         stdout.write(plan.snippet);
         return 0;
     }
-    const steps = nextSteps(clientId, auth, serverName, project);
+    const steps = nextSteps(clientId, auth, serverName, project, scope, isReadOnlyUrl(url));
     if (plan.kind === "manual") {
         out(plan.hint);
         stdout.write(plan.snippet);
@@ -883,6 +1070,9 @@ export async function runMcpCommand(argv, io = {}) {
             return 0;
         }
         let failed = false;
+        // `codex mcp add` signs in at once and waits up to five minutes for the browser. Outside a
+        // terminal (CI, an agent's shell tool) nobody may finish that, so a default sign-in prints it.
+        const deferCodex = auth === "oauth" && explicitAuth === undefined && !isTerminal(stdout);
         for (const command of plan.commands) {
             const executable = await findExecutable(command.executable, env);
             if (!executable) {
@@ -891,12 +1081,36 @@ export async function runMcpCommand(argv, io = {}) {
                 out(command.display);
                 continue;
             }
+            if (deferCodex && command.executable === "codex") {
+                out("Not running codex mcp add: it signs in at once and waits up to 5 minutes for the browser, and no terminal is attached. Run it where you can sign in, or pass --auth oauth to run it here and wait:");
+                out(command.display);
+                continue;
+            }
+            // What Codex held before, so a failed add is not mistaken for this run's registration.
+            const codexSignIn = auth === "oauth" && command.executable === "codex";
+            const before = codexSignIn
+                ? await readCodexEntry(executable, serverName, { cwd, env })
+                : undefined;
             out(`Running: ${shownCommand(command)}`);
             const code = await runClientCli(executable, command.args, { cwd, env, stdout, stderr });
             if (code === 0) {
                 out(`Registered the "${serverName}" MCP server (${shownUrl}) with ${command.label}.`);
                 continue;
             }
+            // Codex writes its entry before signing in, so a sign-in that timed out or was denied
+            // leaves the server registered; `codex mcp login` signs in again. Only an entry this run
+            // wrote counts: one Codex already held unchanged proves nothing about this add.
+            if (code !== null && codexSignIn) {
+                const after = await readCodexEntry(executable, serverName, { cwd, env });
+                const wrote = after.state === "found" &&
+                    after.entry.auth === "oauth" &&
+                    after.entry.url === url &&
+                    (before?.state === "none" || (before?.state === "found" && before.raw !== after.raw));
+                if (wrote) {
+                    out(`Registered the "${serverName}" MCP server (${shownUrl}) with Codex, but its sign-in did not finish. Run codex mcp login ${serverName} to sign in.`);
+                    continue;
+                }
+            }
             failed = true;
             stderr.write(`${command.executable} ${code === null ? "could not be started" : `exited with code ${code}`}. Run this command yourself:\n${command.display}\n`);
         }

package/dist/environment/world.d.ts

@@ -23,10 +23,12 @@ export interface AgentEnvironmentOptions {
      * default; the canonical carriers are the world's own `env`. */
     legacyMcpVariables?: boolean;
 }
+/** `environment` without any variable a world or its server owns. */
+export declare function withoutWorldVariables(environment: Record<string, string>): Record<string, string>;
 /**
  * The environment for an agent child process running one case (the coordination briefs'
- * recommended policy): the parent's variables minus Hue control-plane credentials, then the
- * world's carriers, which win over anything the parent set. Nothing here is logged.
+ * recommended policy): the parent's variables minus Hue control-plane credentials and any
+ * world-scoped variable, then the world's carriers. Nothing here is logged.
  */
 export declare function agentEnvironment(world: WorldHandoff, options?: AgentEnvironmentOptions): Record<string, string>;
 /** The `{ url, token, expiresAt }` shape the `hue_sim_` capability had, projected from the

package/dist/environment/world.js

@@ -53,16 +53,25 @@ export function stripHueControlPlaneCredentials(parent) {
     }
     return child;
 }
+/** Variables a world or its server owns: a parent's value belongs to another world (a runner
+ * started inside a case, a shell left from an earlier run) or to the server (a signing key), and
+ * would send this world's token to a mirror this world does not have. The whole `HUE_WORLD_`
+ * prefix is the world's. */
+const WORLD_SCOPED = /^(?:HUE_WORLD_[A-Z0-9_]+|HUE_MCP_(?:CONFIG|URL|TOKEN|EXPIRES_AT)|HUE_SIM_[A-Z0-9_]+_(?:URL|ALIAS))$/;
+/** `environment` without any variable a world or its server owns. */
+export function withoutWorldVariables(environment) {
+    return Object.fromEntries(Object.entries(environment).filter(([name]) => !WORLD_SCOPED.test(name)));
+}
 /**
  * The environment for an agent child process running one case (the coordination briefs'
- * recommended policy): the parent's variables minus Hue control-plane credentials, then the
- * world's carriers, which win over anything the parent set. Nothing here is logged.
+ * recommended policy): the parent's variables minus Hue control-plane credentials and any
+ * world-scoped variable, then the world's carriers. Nothing here is logged.
  */
 export function agentEnvironment(world, options = {}) {
     const parent = options.parent ?? process.env;
-    const child = options.includeHueCredentials
+    const child = withoutWorldVariables(options.includeHueCredentials
         ? Object.fromEntries(Object.entries(parent).filter((entry) => entry[1] !== undefined))
-        : stripHueControlPlaneCredentials(parent);
+        : stripHueControlPlaneCredentials(parent));
     Object.assign(child, world.env);
     if (options.legacyMcpVariables ?? true) {
         const legacy = legacyMcpCapability(world);

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.11.3";
+export declare const sdkVersion = "0.11.4";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.11.3";
+export const sdkVersion = "0.11.4";

package/package.json

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