@hue-run/sdk 0.8.0 → 0.9.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.8.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.9.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.
 
@@ -157,9 +157,13 @@ project. Run them separately with different keys if you want to revoke either us
 ```sh
 hue login                                  # one key for both uses into ./.env.hue
 hue login --keys coding-agent --gitignore  # only HUE_MCP_KEY; add .env.hue to .gitignore
-hue login --origin https://staging.hue.run --env-file .env.staging
+hue login --origin https://staging.hue.run --env-path .env.staging
 ```
 
+`--env-path <path>` writes another env file, creating it when missing. `--env-file <path>` is
+accepted too, but Node 22 and 24 read that flag from the whole command line and exit with
+`node: <path>: not found` before `hue` runs when the file does not exist yet.
+
 The env file is written with mode `0600` through a temporary file and an atomic rename. Other
 lines are preserved; a symlink or a non-regular file is refused; an existing different value is
 replaced only with `--force`. Empty values, whitespace and URLs are refused before any request.
@@ -301,7 +305,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.8.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.9.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -312,7 +316,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.8.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.9.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -375,7 +379,8 @@ hue eval --worker ./hue-agent.ts --agent-key support-agent --env-file .env.hue
 
 The one-shot mode resolves the selection (`--case` by name, ID or URL; `--set` by name, ID or
 URL with explicit `--scorer-version` pins; or `--dataset-version` with `--scorer-version`),
-creates a fresh run from those immutable pins named `<case> · <agent key> · <revision>`
+creates a fresh run from those immutable pins named `<agent key> @ <revision>` (a commit hash is
+shortened to 7 characters)
 (`--name` overrides), prints `Run: <url>` and `Experiment: <id>` as soon as the experiment exists,
 one line per case event (world created, agent started, world sealed), then
 `Waiting for Hue checks...` and a table with one row per case: boolean metrics as `PASS`/`FAIL`,
@@ -411,7 +416,7 @@ apply; Hue chooses the pinned experiment. The worker exits 0 when it stops norma
 A Scenario or eval set whose dataset version is not saved cannot back an experiment: the command
 exits 1 and asks for **Save eval-set version** in Hue or `--save-version`, which freezes that
 version at its current revision. Connection settings are `HUE_API_KEY` and `HUE_BASE_URL`
-(default `https://app.hue.run`), loaded from `--env-file <path>` first when given; `--origin`
+(default `https://app.hue.run`), loaded from `--env-file <path>` (or its alias `--env-path`) first when given; `--origin`
 overrides the origin. Telemetry content capture stays off unless `--content` is passed; in
 one-shot mode it also decides whether case outputs, error messages and explanations are persisted
 to Hue. `--worker` always persists them, because a run launched from Hue is read on its run page:

package/ENVIRONMENTS.md

@@ -126,6 +126,18 @@ Hue canonicalizes valid synthetic-principal UUIDs to lowercase, and repository r
 the same before comparing immutable digests, so casing-only UUID changes reuse the stored
 version without dropping provider bindings.
 
+Each Gmail provider instance names its mailbox carrier in `configuration`
+(`GmailMailboxConfiguration`, narrowed by `kind`). `gmail_mailbox/v1` binds `messagesCollection`
+and `draftsCollection` in the simplified shape Hue's `hue.gmail.*` actions read.
+`gmail_mailbox/v2` adds `labelsCollection` and binds all three in the entity shapes the Gmail
+mirrors serve: messages may also carry `cc`, `bcc`, `htmlBody`, `snippet`, attachment metadata,
+`sizeEstimate`, `historyId` and `raw`, each draft names a `DRAFT`-labelled message, and threads
+are derived from each message's `threadId`. Only the simulation gateway serves it: the pinned
+provider-profile preflight above reports `profile_unavailable` for a `gmail_mailbox/v2`
+instance. Its `mailboxAddress` must be the synthetic owner `owner@example.test` (compared
+case-insensitively) or publication is refused, and a definition whose provider instances all use
+it may publish with `actions: []`.
+
 ```ts
 const definition = {
   kind: "repository" as const,
@@ -183,7 +195,8 @@ await client.finishRun(run.id, { idempotencyKey: randomUUID(), status: "complete
 ```
 
 Each bound call is an ordinary `hue.tool` span. When the catalog names an MCP server, the span
-also carries `mcp.server.name`. Wrap any MCP client the same way, using `serverInfo` from
+also carries `mcp.server.name`, plus `hue.mcp.provider` and `hue.mcp.surface` when the catalog
+entry includes them. Wrap any MCP client the same way, using `serverInfo` from
 `initialize` — this is not specific to Hue-hosted Gmail or Slack:
 
 ```ts
@@ -229,22 +242,38 @@ try {
   await spawnAgent({ env: child, mcpConfigPath: config.path });
 } finally {
   await config.dispose();
-  await environmentClient.finishRun(run.id, {
+  const finished = await environmentClient.finishRun(run.id, {
     idempotencyKey: `execution:${executionId}:completed`,
     status: "completed",
   });
+  const graceEnd = Date.parse(finished.completingUntil ?? "") || Date.now();
+  await new Promise((resolve) =>
+    setTimeout(resolve, Math.min(10_000, Math.max(0, graceEnd - Date.now()))),
+  );
+  const sealDeadline = Date.now() + 30_000;
+  let sealed = false;
+  while (Date.now() < sealDeadline) {
+    if ((await environmentClient.getRun(run.id)).status !== "open") {
+      sealed = true;
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  if (!sealed) throw new Error("World was not sealed after its completion grace");
 }
 ```
 
 `runSimulation`, `runLocalAgent` and `hue eval` do this for you: they create the world with the
 execution, the stable key, the case span's context and the agent revision, pass the handoff as
-`context.world`, and finish before returning so telemetry is flushed and the execution completed
-afterwards. For one compatibility release `context.mcp` is the world's first MCP mirror with the
+`context.world`, and finish and wait for the seal before returning so telemetry is flushed and the
+execution completed afterwards. For one compatibility release `context.mcp` is the world's first MCP mirror with the
 world token, so an adapter that read `HUE_MCP_URL` and `HUE_MCP_TOKEN` keeps working;
 `agentEnvironment` sets those names too unless `legacyMcpVariables: false`. A gateway world binds
 no Hue-native `tools` (Hue refuses them); a world created while the gateway is off keeps its tools
 and the `hue_sim_` capability and emits a one-time `DeprecationWarning`.
 
+A refusal such as 409 `simulation_gateway_required` exposes its validated server code as `HueEnvironmentError.diagnostic`.
+
 `agentEnvironment` removes Hue control-plane credentials from the child by default: `HUE_API_KEY`,
 `HUE_MCP_KEY` and any variable whose value is a `hue_sk_`, `hue_mcp_` or `hue_attempt_`
 credential. Pass `includeHueCredentials: true` only for an agent that must call Hue's own API.
@@ -252,7 +281,9 @@ Nothing in these helpers logs the token; keep it out of your own logs and checkp
 
 Finish answers `lifecycle: "completing"` with `sealedAt: null` for a gateway world: the seal
 follows a 5 s grace so in-flight writes land, and a late finish answers 409, which the helpers
-treat as the seal they can no longer change. `getEvidence(runId, { section, bodies })` reads the
+treat as the seal they can no longer change. Completing an execution while the world is open
+returns 409, so direct clients read the run after the finish response's `completingUntil`
+until it is no longer open; the helper waits through transient failures. `getEvidence(runId, { section, bodies })` reads the
 sealed world's evaluator-only evidence (start and end state, the diff, the call ledger, coverage,
 fingerprint) with the project key; a world token can never read it. The client honors Hue's
 `Retry-After` on 429 and 503.

package/README.md

@@ -131,22 +131,82 @@ await hue.model(
 );
 ```
 
+Tools the provider runs itself, such as OpenAI hosted MCP, web search, file search and code
+interpreter, or Anthropic's MCP connector and server tools, never pass through `hue.tool()`. Inside
+the same `hue.model()` callback, hand the response to `hue.recordProviderToolCalls`:
+
+```ts
+await hue.model(
+  "gpt-5-mini",
+  async (span) => {
+    const response = await openai.responses.create(request);
+    span.setOutput(response.output_text);
+    hue.recordProviderToolCalls(response, { request });
+    return response;
+  },
+  { provider: "openai" },
+);
+```
+
+Each OpenAI Responses `mcp_call`, `web_search_call`, `file_search_call` or `code_interpreter_call`
+item, and each Anthropic `mcp_tool_use` or `server_tool_use` block with its result, becomes an
+`execute_tool {name}` child span with `gen_ai.tool.type` `extension`, `gen_ai.tool.call.id` and,
+for MCP calls, `mcp.server.name` (the provider's label). Arguments and results follow
+`captureContent`; a failed call carries `error.type` (`mcp_error`, the provider's status or error
+code) and ERROR status. An `mcp_list_tools` item becomes a `tools/list` child span with that
+server's `gen_ai.tool.definitions`. Pass the request so each server's host is recorded as
+`server.address` (only server URLs are read, never credentials), and `servers` to record a
+server's real `name`, `version`, Hue `provider` and `surface` under its label. `provider` defaults
+to the enclosing `model()` call's provider (`openai` or `anthropic`). The spans have no duration of
+their own: the provider ran the tools inside the model request.
+
 The span is named `{operation} {model}` (`operation` defaults to `chat`) with
 `gen_ai.operation.name`, `gen_ai.request.model` and `gen_ai.provider.name`. Like `withSpan`, the
-options come after the callback and also accept `name`, `sessionId`, `userId`, `input` (recorded as
-`gen_ai.input.messages`) and `parentContext`. `setUsage` records
+options come after the callback and also accept `name`, `sessionId`, `userId`, `workspaceId`, `input` (recorded as
+`gen_ai.input.messages`) and `parentContext`. When you send system instructions or tools separately
+from the messages, pass `systemInstructions` (for example `[{ type: "text", content: instructions }]`)
+and `tools` (for example `[{ type: "function", name, description, parameters }]`); they are recorded
+as `gen_ai.system_instructions` and `gen_ai.tool.definitions` under the same `captureContent` rule
+as the messages. `recordMessages` also accepts `systemInstructions` for its log record. `setUsage` records
 nonnegative integer `gen_ai.usage.input_tokens` / `output_tokens`; other values are omitted and
 counted as instrumentation failures. Unknown usage stays absent. `hue.tool(name, input, execute)`
 creates an `execute_tool {name}` span with `gen_ai.tool.name`, arguments and result; an optional
 fourth argument `{ callId }` records the provider's tool call id as `gen_ai.tool.call.id`. When the
 tool came from an MCP server, pass `{ mcp: client.getServerVersion() }` (the MCP `initialize`
 `serverInfo`) to record `mcp.server.name` and `mcp.server.version` so a generic verb such as
-`get_thread` is attributed to that server. Content
+`get_thread` is attributed to that server. When the server is a Hue surface, `mcp.provider` and
+`mcp.surface` (for example `google.gmail` and `google.gmail/mcp`) record `hue.mcp.provider` and
+`hue.mcp.surface`. A blank, over-256-character or otherwise invalid label is omitted and counted as
+an instrumentation failure; the tool still runs. Content
 helpers (`setInput`, `setOutput`, `tool` arguments and results, `recordMessages`,
 `SpanOptions.input`) accept any value and encode plain JSON data (`JsonValue`) at runtime; a value
 that is not JSON, such as a `Date` or a class instance, is omitted with an instrumentation failure
 while the callback result is returned unchanged.
 
+## Files
+
+Record a file the work read, received or produced with `hue.recordFile`. It adds a `hue.file`
+event to the active span (or the span of an explicit context passed second), keyed by the file's
+SHA-256, so a trace can be linked to the same file elsewhere without exporting its bytes:
+
+```ts
+import { readFile } from "node:fs/promises";
+
+await hue.withSpan("review contract", async () => {
+  const pdf = await readFile("contract.pdf");
+  hue.recordFile({ role: "input", mediaType: "application/pdf", data: pdf, name: "contract.pdf" });
+  // ...
+});
+```
+
+`data` up to 25 MiB is hashed and measured locally and never exported; larger data is omitted and
+counted as an instrumentation failure, so pass `sha256` (and `byteSize`) instead when you already
+have them. The event carries `hue.file.sha256`, `hue.file.role` (`input`,
+`attachment` or `output`), `hue.file.media_type` and `hue.file.size`. It is metadata, so it is
+recorded in both capture modes, while `hue.file.name` is recorded only when `captureContent` is
+true. An invalid record, or one without an active span, is omitted and counted as an
+instrumentation failure.
+
 ## Vercel AI SDK 6
 
 AI SDK 6 accepts a per-call tracer through `experimental_telemetry`. Pass
@@ -216,6 +276,15 @@ instrumentations can use `hue.tracer` directly or explicitly attach the processo
 below. Instrumentations that only use a global provider need your application's
 normal OTel setup; Hue does not silently replace it.
 
+Provider-executed tools, such as OpenAI hosted MCP (`openai.tools.mcp`), appear as
+`execute_tool mcp.<name>` spans with `gen_ai.tool.type` `extension`. The server is named only
+by `serverLabel` inside the recorded result, so before export the TypeScript SDK copies it to
+`mcp.server.name`, and a result with an MCP `error` sets ERROR status and `error.type`
+`mcp_error`. Metadata-only export keeps these two attributes while stripping arguments and
+results. The label can only be read when AI SDK recorded the result: `hueTelemetry(hue)` with
+`captureContent: false` records none, whereas an application whose AI SDK integration records
+outputs and exports through Hue's attached processors keeps the label.
+
 ## Privacy and content
 
 `captureContent: false` disables manual input/output/messages/tool content and
@@ -232,6 +301,36 @@ attributes, resources, event/link attributes and log bodies. Return a string.
 Invalid/oversized helper content is omitted with an instrumentation failure; the span can still be delivered. Export-time redactor failures reject the affected record and are reported by flush. Shared resources are redacted once per
 export batch. Do not put user content or secrets in span names or scope names.
 
+Hosted tools carry credentials in their definitions, such as the `authorization` and `headers` of
+an OpenAI hosted MCP tool. Before export, and before `redact`, Hue replaces the values of
+credential-like fields including `authorization`, `authorization_token`, `headers`, `api_key`,
+`access_token`, `x-api-key`, and keys ending in `token`, `secret`, `password`, `apikey` or
+`credential` (case-insensitively, ignoring `-` and `_`) with `"[redacted]"` in recorded tool definitions
+(`gen_ai.tool.definitions`, `ai.prompt.tools`, `llm.tools.*.tool.json_schema`) and in the `tools`
+and `mcp_servers` entries of a raw provider request or response recorded as `input.value`,
+`output.value` or `llm.invocation_parameters`. Parameters named in a JSON Schema `properties`
+object keep their schemas, so a tool that takes a `headers` argument is still described. A
+definition nested more than 256 levels deep rejects its record. Sensitive `default`, `const`,
+`examples` and `enum` values under credential-named schema parameters are redacted too.
+
+With `captureContent: false`, export removes tool definitions but keeps a summary of them on the
+same record: `hue.tool.names` lists each definition's `name` (Chat Completions `function.name`,
+or the `type` of an unnamed built-in tool such as `mcp`) in order, and
+`hue.tool.definitions.sha256` is the lowercase hex SHA-256 of the
+[RFC 8785](https://www.rfc-editor.org/rfc/rfc8785) canonical JSON of the credential-scrubbed
+definition list. The digest is the same in both SDKs and does not change when a credential
+rotates. Only definitions another integration recorded can be summarized: `hueTelemetry(hue)` with
+`captureContent: false` records none, whereas an application whose AI SDK integration records
+inputs and exports through Hue's attached processors gets the summary.
+Recorded messages can inline files: GenAI `blob` parts in `gen_ai.input.messages` /
+`gen_ai.output.messages` (what the AI SDK 7 adapter records for a file part) and AI SDK 6 `file`
+parts in `ai.prompt.messages`. A span whose messages exceed 256 KiB would be rejected, so before
+export Hue replaces the `content`/`data` of any such part longer than 64 KiB with the file's
+`sha256` (of the decoded bytes for base64 and `data:` URLs, of the UTF-8 text otherwise) and
+`size`, keeping the part's other fields such as `type`, `mime_type` and `mediaType`. Smaller inline
+files are exported as recorded. The digest matches `hue.recordFile`'s `hue.file.sha256` for the same
+bytes, so a file can be recognized wherever it appears.
+
 Manual helpers encode JSON values without converting null into absence. Unknown
 outputs and usage remain absent. This SDK does not estimate tokens or cost. A thrown
 application error marks the span with `error.type` (the error's `name`), an ERROR status and an
@@ -281,7 +380,9 @@ For external parent context pass `parentContext` to `withSpan`. Across processes
 speak W3C `traceparent` only and never include the API key or baggage. Hue registers no global
 propagator, so `propagation.inject()` from `@opentelemetry/api` is a no-op unless your
 application configured one. `getContext()` exposes the helper's current context for APIs taking
-an explicit context. Session/user identifiers are inherited within a client callback and are
+an explicit context. Session, user and workspace identifiers (`sessionId` as
+`gen_ai.conversation.id`, `userId` as `user.id`, and `workspaceId` as `hue.workspace.id` for the
+application workspace or tenant) are inherited within a client callback and are
 stamped only on spans created through Hue's tracer (helpers and the AI SDK adapters); spans from
 other instrumentations on a shared provider carry them only if that instrumentation sets them.
 Separate requests require separate callbacks.

package/dist/ai-sdk.d.ts

@@ -2,9 +2,9 @@ import type { TelemetryOptions } from "ai";
 import type { HueClient } from "./client.js";
 /**
  * Per-call telemetry for AI SDK 7: pass as an agent's or generation call's `telemetry` option.
- * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session/user
- * identifiers; prompt and response recording follow `captureContent`. It does not change global
- * AI SDK integrations.
+ * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session, user and
+ * workspace identifiers; prompt and response recording follow `captureContent`. It does not
+ * change global AI SDK integrations.
  *
  * @throws TypeError when the client is enabled and the installed `ai` major version is below 7;
  * AI SDK 6 applications use `hueExperimentalTelemetry` from `@hue-run/sdk` instead.

package/dist/ai-sdk.js

@@ -21,9 +21,9 @@ function aiMajor() {
 }
 /**
  * Per-call telemetry for AI SDK 7: pass as an agent's or generation call's `telemetry` option.
- * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session/user
- * identifiers; prompt and response recording follow `captureContent`. It does not change global
- * AI SDK integrations.
+ * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session, user and
+ * workspace identifiers; prompt and response recording follow `captureContent`. It does not
+ * change global AI SDK integrations.
  *
  * @throws TypeError when the client is enabled and the installed `ai` major version is below 7;
  * AI SDK 6 applications use `hueExperimentalTelemetry` from `@hue-run/sdk` instead.

package/dist/cli/env-file.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Node 22 and 24 scan the whole command line for `--env-file`, including arguments meant for the
+ * script, and exit with "node: <path>: not found" before the CLI runs when that file does not
+ * exist. `--env-path` is the same option under a name Node ignores, so a command such as
+ * `hue login` can name a file it is about to create.
+ */
+export declare const envFileOptions: {
+    readonly "env-file": {
+        readonly type: "string";
+    };
+    readonly "env-path": {
+        readonly type: "string";
+    };
+};
+/**
+ * The env file named by `--env-path` or `--env-file`; throws when both name different files,
+ * comparing them as resolved from `cwd`.
+ */
+export declare function envFileArgument(values: {
+    "env-file"?: string | undefined;
+    "env-path"?: string | undefined;
+}, cwd: string): string | undefined;

package/dist/cli/env-file.js

@@ -0,0 +1,21 @@
+import { resolve } from "node:path";
+/**
+ * Node 22 and 24 scan the whole command line for `--env-file`, including arguments meant for the
+ * script, and exit with "node: <path>: not found" before the CLI runs when that file does not
+ * exist. `--env-path` is the same option under a name Node ignores, so a command such as
+ * `hue login` can name a file it is about to create.
+ */
+export const envFileOptions = {
+    "env-file": { type: "string" },
+    "env-path": { type: "string" },
+};
+/**
+ * The env file named by `--env-path` or `--env-file`; throws when both name different files,
+ * comparing them as resolved from `cwd`.
+ */
+export function envFileArgument(values, cwd) {
+    const { "env-file": file, "env-path": path } = values;
+    if (file !== undefined && path !== undefined && resolve(cwd, file) !== resolve(cwd, path))
+        throw new Error("Pass one of --env-file and --env-path, not both.");
+    return path ?? file;
+}

package/dist/cli/eval.js

@@ -17,6 +17,7 @@ import { matchByName, parseScenarioSelector, resolveEvalSetPins, resolveScenario
 import { collectDirectOutputs, stageDirectCase } from "./eval-direct.js";
 import { runSimulation, } from "../evals/simulation.js";
 import { collectExperimentVerdicts, compareVerdicts, metricPassed, } from "../evals/verdicts.js";
+import { envFileArgument, envFileOptions } from "./env-file.js";
 const USAGE = `Usage: hue eval [adapter-file] [options]
 
 Run a local agent against a published case or eval set, then print Hue's verdicts.
@@ -56,10 +57,11 @@ Modes:
 
 Connection:
   --env-file <path>               Load a dotenv file (HUE_API_KEY, HUE_BASE_URL) first
+  --env-path <path>               Same as --env-file
   --origin <url>                  Hue origin (default: HUE_BASE_URL or https://app.hue.run)
 
 Output and limits:
-  --name <run name>               Run name (default: <case> · <agent key> · <revision>)
+  --name <run name>               Run name (default: <agent key> @ <revision>, hashes shortened)
   --baseline <experiment id|url>  Compare verdicts with a previous experiment
   --json                          Print one JSON document on stdout; progress goes to stderr
   --content                       Capture telemetry content; one-shot also persists
@@ -105,7 +107,7 @@ function parse(argv) {
                 "agent-key": { type: "string" },
                 "agent-name": { type: "string" },
                 revision: { type: "string" },
-                "env-file": { type: "string" },
+                ...envFileOptions,
                 origin: { type: "string" },
                 name: { type: "string" },
                 baseline: { type: "string" },
@@ -172,6 +174,12 @@ function derivedAgentKey(adapterFile, command) {
         "";
     return slug(basename(script, extname(script)));
 }
+function defaultRunName(agent) {
+    const revision = /^[0-9a-f]{12,64}$/i.test(agent.revision)
+        ? agent.revision.slice(0, 7)
+        : agent.revision;
+    return `${agent.key} @ ${revision}`;
+}
 function gitRevision() {
     try {
         const value = execFileSync("git", ["rev-parse", "--short=12", "HEAD"], {
@@ -692,7 +700,7 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
         const frozen = await client.freezeDatasetVersion(pins.datasetVersionId, pins.revision);
         output.log(`Saved "${pins.name}" version ${frozen.version}.`);
     }
-    const runName = values.name ?? `${pins.name} · ${agent.key} · ${agent.revision}`;
+    const runName = values.name ?? defaultRunName(agent);
     const project = await client.checkConnection();
     if (await detectDirect(client, pins, mode))
         return runDirect({
@@ -976,12 +984,19 @@ export async function runEvalCommand(argv) {
             throw new UsageError("--worker takes no selection; Hue chooses the run to execute");
         if (!values.worker && selections !== 1)
             throw new UsageError("Pass exactly one of --case, --set or --dataset-version");
-        if (values["env-file"]) {
+        let envFile;
+        try {
+            envFile = envFileArgument(values, process.cwd());
+        }
+        catch (error) {
+            throw new UsageError(error.message);
+        }
+        if (envFile) {
             try {
-                process.loadEnvFile(resolve(values["env-file"]));
+                process.loadEnvFile(resolve(envFile));
             }
             catch (error) {
-                throw new UsageError(`Unable to load ${values["env-file"]}: ${error instanceof Error ? error.message : String(error)}`);
+                throw new UsageError(`Unable to load ${envFile}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         const apiKey = process.env.HUE_API_KEY?.trim();

package/dist/cli/login.d.ts

@@ -14,7 +14,7 @@ export interface LoginCommandIo {
     fetch?: typeof fetch;
     openBrowser?: (url: string) => Promise<boolean>;
 }
-export declare const LOGIN_USAGE = "Usage: hue login [--origin URL] [--env-file PATH] [--keys evaluations|coding-agent|both]\n                 [--no-browser] [--force] [--gitignore]\n\nStore the key you created in Hue in a private env file. By default one \"Read and write\" key serves\nboth evaluations (HUE_API_KEY) and your coding agent (HUE_MCP_KEY); it is validated against Hue\nbefore it is stored, and key values are never printed.\n\nOptions:\n  --origin URL     Hue origin (default https://app.hue.run)\n  --env-file PATH  Env file to write (default .env.hue in the current directory)\n  --keys KIND      evaluations (HUE_API_KEY), coding-agent (HUE_MCP_KEY) or both from one key\n                   (default both)\n  --no-browser     Do not open the key settings page in a browser\n  --force          Replace an existing different value in the env file\n  --gitignore      Add the env file to .gitignore when a git repository does not ignore it\n  -h, --help       Show this help";
+export declare const LOGIN_USAGE = "Usage: hue login [--origin URL] [--env-path PATH] [--keys evaluations|coding-agent|both]\n                 [--no-browser] [--force] [--gitignore]\n\nStore the key you created in Hue in a private env file. By default one \"Read and write\" key serves\nboth evaluations (HUE_API_KEY) and your coding agent (HUE_MCP_KEY); it is validated against Hue\nbefore it is stored, and key values are never printed.\n\nOptions:\n  --origin URL     Hue origin (default https://app.hue.run)\n  --env-path PATH  Env file to write (default .env.hue in the current directory); it is\n                   created when missing. --env-file also works, but Node itself exits\n                   before this command runs when that file does not exist yet\n  --keys KIND      evaluations (HUE_API_KEY), coding-agent (HUE_MCP_KEY) or both from one key\n                   (default both)\n  --no-browser     Do not open the key settings page in a browser\n  --force          Replace an existing different value in the env file\n  --gitignore      Add the env file to .gitignore when a git repository does not ignore it\n  -h, --help       Show this help";
 /** Hue MCP endpoint that pairs with an application origin. */
 export declare function mcpUrlForOrigin(origin: string): string;
 /** Normalizes a Hue origin: HTTPS, or HTTP for loopback only; no credentials, path, query or hash. */

package/dist/cli/login.js

@@ -7,6 +7,7 @@ import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
 import { parseArgs } from "node:util";
 import { isLoopbackHost } from "../config.js";
+import { envFileArgument, envFileOptions } from "./env-file.js";
 const DEFAULT_ORIGIN = "https://app.hue.run";
 const DEFAULT_ENV_FILE = ".env.hue";
 /** Settings section that lists and creates project service keys. */
@@ -27,7 +28,7 @@ const KEY_KINDS = {
 };
 /** Settings preset that authorizes both evaluations and the coding agent's MCP reads and writes. */
 const KEY_PRESET = "Read and write";
-export const LOGIN_USAGE = `Usage: hue login [--origin URL] [--env-file PATH] [--keys evaluations|coding-agent|both]
+export const LOGIN_USAGE = `Usage: hue login [--origin URL] [--env-path PATH] [--keys evaluations|coding-agent|both]
                  [--no-browser] [--force] [--gitignore]
 
 Store the key you created in Hue in a private env file. By default one "Read and write" key serves
@@ -36,7 +37,9 @@ before it is stored, and key values are never printed.
 
 Options:
   --origin URL     Hue origin (default ${DEFAULT_ORIGIN})
-  --env-file PATH  Env file to write (default ${DEFAULT_ENV_FILE} in the current directory)
+  --env-path PATH  Env file to write (default ${DEFAULT_ENV_FILE} in the current directory); it is
+                   created when missing. --env-file also works, but Node itself exits
+                   before this command runs when that file does not exist yet
   --keys KIND      evaluations (HUE_API_KEY), coding-agent (HUE_MCP_KEY) or both from one key
                    (default both)
   --no-browser     Do not open the key settings page in a browser
@@ -558,7 +561,7 @@ function parseLoginArguments(argv) {
         strict: true,
         options: {
             origin: { type: "string" },
-            "env-file": { type: "string" },
+            ...envFileOptions,
             keys: { type: "string" },
             "no-browser": { type: "boolean", default: false },
             force: { type: "boolean", default: false },
@@ -591,8 +594,10 @@ export async function runLoginCommand(argv, io = {}) {
         return code;
     };
     let parsed;
+    let envFileOption;
     try {
         parsed = parseLoginArguments(argv);
+        envFileOption = envFileArgument(parsed.values, cwd);
     }
     catch (error) {
         return fail(`${error.message}\n\n${LOGIN_USAGE}`, 2);
@@ -615,7 +620,7 @@ export async function runLoginCommand(argv, io = {}) {
     if (!origin)
         return fail("--origin must be an HTTPS origin such as https://app.hue.run (plain HTTP is accepted for loopback test servers only).", 2);
     const mcpUrl = mcpUrlForOrigin(origin);
-    const envPath = resolve(cwd, parsed.values["env-file"] ?? DEFAULT_ENV_FILE);
+    const envPath = resolve(cwd, envFileOption ?? DEFAULT_ENV_FILE);
     const envDisplay = displayPath(cwd, envPath);
     let envFile;
     try {

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type Context, type Span, type Tracer } from "@opentelemetry/api";
 import { HueTransport } from "./transport.js";
-import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, ModelOptions, ProjectConnection, SpanOptions, ToolOptions, VerifyTraceOptions, TraceVerification, SafeLifecycleOptions, SafeLifecycleResult } from "./types.js";
+import type { ExportReport, FileRecord, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, ModelOptions, ProjectConnection, SpanOptions, ProviderToolCallOptions, ToolOptions, VerifyTraceOptions, TraceVerification, SafeLifecycleOptions, SafeLifecycleResult } from "./types.js";
 /**
  * Attach mode: the application owns its OpenTelemetry providers and passes the transport whose
  * processors it attached to them. The client flushes these providers but never shuts them down.
@@ -75,7 +75,8 @@ export declare class HueClient {
      * `options.callId` is recorded as `gen_ai.tool.call.id`, like the Python `call_id=` keyword.
      * `options.mcp` records the MCP `initialize` `serverInfo` as `mcp.server.name` /
      * `mcp.server.version` so a generic tool name can be attributed to the server that
-     * handled it. Pass `client.getServerVersion()`.
+     * handled it. Pass `client.getServerVersion()`. `mcp.provider` / `mcp.surface` record the Hue
+     * provider and surface as `hue.mcp.provider` / `hue.mcp.surface`.
      */
     tool<T>(name: string, input: unknown, execute: () => Promise<T> | T, options?: ToolOptions): Promise<T>;
     /**
@@ -84,7 +85,8 @@ export declare class HueClient {
      * `gen_ai.request.model` and `gen_ai.provider.name`. The argument order matches `withSpan`. The
      * handle's `setInput`/`setOutput` record `gen_ai.input.messages` / `gen_ai.output.messages`,
      * which should use the GenAI semantic-convention message shape; `recordMessages` inside the
-     * callback inherits the request metadata.
+     * callback inherits the request metadata. `options.systemInstructions` and `options.tools` are
+     * recorded as `gen_ai.system_instructions` and `gen_ai.tool.definitions`, content like `input`.
      */
     model<T>(model: string, callback: (span: HueSpan) => Promise<T> | T, options: ModelOptions): Promise<T>;
     private setUsage;
@@ -113,6 +115,8 @@ export declare class HueClient {
         input?: unknown;
         /** Output messages, ideally in the GenAI semantic-convention shape; any JSON-encodable value. */
         output?: unknown;
+        /** System instructions sent separately from the messages, as `gen_ai.system_instructions`. */
+        systemInstructions?: unknown;
         /** `gen_ai.operation.name` for the record; defaults to the enclosing `model()` span's value. */
         operation?: string;
         /** `gen_ai.provider.name` for the record; defaults to the enclosing `model()` span's value. */
@@ -120,6 +124,30 @@ export declare class HueClient {
         /** `gen_ai.request.model` for the record; defaults to the enclosing `model()` span's value. */
         model?: string;
     }, explicitContext?: Context): void;
+    /**
+     * Records the tools a model provider executed itself while producing `response`, which no
+     * `hue.tool()` call saw: OpenAI Responses `mcp_call`, `web_search_call`, `file_search_call` and
+     * `code_interpreter_call` items, and Anthropic Messages `mcp_tool_use` / `server_tool_use`
+     * blocks with their result blocks. Each becomes an `execute_tool {name}` child span of the active
+     * (or given) context with `gen_ai.tool.type` `extension` and `gen_ai.tool.call.id`; MCP calls add
+     * `mcp.server.name` (the provider's label, or the `servers` entry for it). Arguments and results
+     * follow `captureContent`; a failed call carries `error.type` and ERROR status. An OpenAI
+     * `mcp_list_tools` item becomes a `tools/list` child span carrying that server's tools as
+     * `gen_ai.tool.definitions`. Call it inside `hue.model()` so the spans nest under the model call
+     * and `provider` defaults to its provider; pass `request` to record each server's host as
+     * `server.address`. The spans have no duration of their own: the provider ran the tools inside
+     * the model request. Unreadable items are skipped and counted; nothing is thrown.
+     */
+    recordProviderToolCalls(response: unknown, options?: ProviderToolCallOptions): void;
+    /**
+     * Adds a `hue.file` event to the active (or given) span for a file the work read, received or
+     * produced: `hue.file.sha256`, `hue.file.role`, `hue.file.media_type`, `hue.file.size` when known
+     * and, when `captureContent` is true, `hue.file.name`. `data` is hashed and measured locally and
+     * never exported. The event is metadata, so it is recorded in both capture modes. An invalid
+     * record, or one without an active span, is omitted and counted, never thrown; an invalid name
+     * alone is omitted and counted while the rest is recorded.
+     */
+    recordFile(file: FileRecord, explicitContext?: Context): void;
     private setContent;
     /**
      * Confirms the key and origin by reading the current project; a setup and CI diagnostic, not a