@hue-run/sdk 0.11.3 → 0.12.0

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/client.d.ts

@@ -43,6 +43,9 @@ export declare class HueClient {
     readonly enabled: boolean;
     private logger;
     private storage;
+    /** Reports a contained capture or instrumentation failure, named to the trace active where
+     * it happened when there is one. */
+    private instrumentationFailed;
     private tracerProvider;
     private loggerProvider;
     private ownedProviders?;

package/dist/client.js

@@ -169,6 +169,20 @@ export class HueClient {
     enabled;
     logger;
     storage = new AsyncLocalStorage();
+    /** Reports a contained capture or instrumentation failure, named to the trace active where
+     * it happened when there is one. */
+    instrumentationFailed(signal = "traces", count = 1) {
+        let traceId;
+        try {
+            traceId = trace
+                .getSpan(this.storage.getStore()?.context ?? context.active())
+                ?.spanContext().traceId;
+        }
+        catch {
+            // The failure is recorded without a trace.
+        }
+        this.transport.instrumentationFailure(signal, undefined, count, traceId);
+    }
     tracerProvider;
     loggerProvider;
     ownedProviders;
@@ -210,7 +224,7 @@ export class HueClient {
         }
         this.captureContent = this.transport.options.captureContent;
         this.enabled = this.transport.options.enabled !== false;
-        this.tracer = new ContextualTracer(this.tracerProvider.getTracer(HUE_SCOPE, sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer(HUE_SCOPE, sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.instrumentationFailed());
         this.logger = this.loggerProvider.getLogger(HUE_SCOPE, sdkVersion);
     }
     /**
@@ -232,7 +246,7 @@ export class HueClient {
             return this.storage.getStore()?.context ?? context.active();
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
             return ROOT_CONTEXT;
         }
     }
@@ -256,7 +270,7 @@ export class HueClient {
                 span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes: options.attributes }, active.context));
             }
             catch {
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
             }
         }
         // A disabled or failed client creates no span; the application's own active span then stays
@@ -268,7 +282,7 @@ export class HueClient {
                 spanContext = trace.setSpan(active.context, span);
             }
             catch {
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
                 spanContext = trace.setSpan(ROOT_CONTEXT, span);
             }
         const handle = {
@@ -287,7 +301,7 @@ export class HueClient {
                     handle.setInput(options.input);
             }
             catch {
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
             }
             try {
                 return await callback(handle);
@@ -303,9 +317,7 @@ export class HueClient {
         // The span is also OpenTelemetry's active span while the callback runs, so spans from other
         // instrumentations (HTTP clients, provider SDKs) join this trace when the application has
         // registered a context manager. Hue still registers none itself.
-        return this.storage.run({ ...active, context: spanContext }, () => created
-            ? runInContext(spanContext, execute, () => this.transport.instrumentationFailure())
-            : execute());
+        return this.storage.run({ ...active, context: spanContext }, () => created ? runInContext(spanContext, execute, () => this.instrumentationFailed()) : execute());
     }
     /**
      * Runs `execute` inside an `execute_tool` span named after the tool. `input` and a defined result
@@ -329,7 +341,7 @@ export class HueClient {
             if (isLabel(value))
                 attributes[key] = value;
             else if (this.enabled && !this.closed)
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
         };
         stamp("gen_ai.tool.call.id", options.callId);
         stamp("mcp.server.name", options.mcp?.name);
@@ -364,7 +376,7 @@ export class HueClient {
             if (isLabel(value))
                 return value;
             if (active)
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
             return fallback;
         };
         const requestModel = label(model, "unknown");
@@ -413,14 +425,14 @@ export class HueClient {
             if (value === undefined)
                 continue;
             if (!Number.isInteger(value) || value < 0) {
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
                 continue;
             }
             try {
                 span.setAttribute(key, value);
             }
             catch {
-                this.transport.instrumentationFailure();
+                this.instrumentationFailed();
             }
         }
     }
@@ -433,7 +445,7 @@ export class HueClient {
             propagator.inject(activeContext, carrier, defaultTextMapSetter);
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
         }
     }
     /** Reads W3C trace context from a carrier for use as `parentContext`. */
@@ -442,7 +454,7 @@ export class HueClient {
             return propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
             return ROOT_CONTEXT;
         }
     }
@@ -461,7 +473,7 @@ export class HueClient {
             span.addEvent("exception", { "exception.type": type });
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
         }
     }
     /**
@@ -498,7 +510,7 @@ export class HueClient {
                 else if (typeof explicit === "string" && explicit.trim() && explicit.length <= 256)
                     attributes[key] = explicit;
                 else
-                    this.transport.instrumentationFailure("logs");
+                    this.instrumentationFailed("logs");
             };
             stamp("gen_ai.operation.name", messages.operation, enclosing?.model?.operation);
             stamp("gen_ai.provider.name", messages.provider, enclosing?.model?.provider);
@@ -513,7 +525,7 @@ export class HueClient {
             });
         }
         catch {
-            this.transport.instrumentationFailure("logs");
+            this.instrumentationFailed("logs");
         }
     }
     /**
@@ -545,7 +557,7 @@ export class HueClient {
             const addresses = hostedServerAddresses(provider, options.request);
             const activity = hostedToolActivity(provider, response);
             if (activity.skipped > 0)
-                this.transport.instrumentationFailure("traces", undefined, activity.skipped);
+                this.instrumentationFailed("traces", activity.skipped);
             const server = (label) => {
                 const attributes = {};
                 if (label === undefined)
@@ -564,7 +576,7 @@ export class HueClient {
                     if (isLabel(value))
                         attributes[key] = value;
                     else
-                        this.transport.instrumentationFailure();
+                        this.instrumentationFailed();
                 }
                 const address = addresses.get(label);
                 if (address !== undefined)
@@ -617,7 +629,7 @@ export class HueClient {
                         span.setAttributes(toolCatalogSummary(encodeContent(listing.definitions, catalogLimits)));
                     }
                     catch {
-                        this.transport.instrumentationFailure();
+                        this.instrumentationFailed();
                     }
                 if (listing.errorType !== undefined)
                     fail(span, listing.errorType);
@@ -625,7 +637,7 @@ export class HueClient {
             }
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
         }
     }
     /**
@@ -692,12 +704,12 @@ export class HueClient {
                 if (isLabel(name))
                     attributes["hue.file.name"] = name;
                 else
-                    this.transport.instrumentationFailure();
+                    this.instrumentationFailed();
             }
             span.addEvent("hue.file", attributes);
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
         }
     }
     setContent(span, key, value) {
@@ -707,7 +719,7 @@ export class HueClient {
             span.setAttribute(key, encodeContent(value));
         }
         catch {
-            this.transport.instrumentationFailure();
+            this.instrumentationFailed();
         }
     }
     /**

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