@hue-run/sdk 0.7.0 → 0.8.1

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.7.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.8.1`, `@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.7.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.8.1.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.7.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.8.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -346,8 +350,9 @@ the CLI never prints it. The optional `zod` peer of `@hue-run/sdk/evals` must be
 
 Write an adapter module that hands the case inputs and the world's tools or MCP connection to
 the real agent. The module exports `default` or `runMyAgent`; `context` is the SDK's
-`SimulationTargetContext` (`tools`, `mcp`, `config`, `item`, `executionId`, `environmentRunId`,
-`signal`):
+`SimulationTargetContext` (`world`, `mcp`, `tools`, `config`, `item`, `executionId`,
+`environmentRunId`, `signal`; `world` carries the provider mirror URLs, the world token, `env` and
+`mcpConfig` where Hue's simulation gateway serves the world):
 
 ```ts
 // hue-agent.ts: erasable TypeScript only; Node.js 24 and Bun strip the types natively.
@@ -374,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`,
@@ -386,12 +392,19 @@ and sends progress to stderr. `--wait <seconds>` (default 300) bounds the verdic
 Hue-owned `world_outcome` checks are graded after the world seals. An experiment always covers
 every case of the saved version; there is no case subset.
 
-`--command "<shell command>"` spawns the command once per case with `HUE_MCP_URL`,
-`HUE_MCP_TOKEN`, `HUE_MCP_EXPIRES_AT`, `HUE_EXECUTION_ID`, `HUE_ENVIRONMENT_RUN_ID`, `HUE_CASE_ID`
-and `HUE_CASE_KEY` in its environment and `{"inputs": ..., "config": ...}` on stdin. Its stdout is
-the answer (JSON when it parses, otherwise trimmed text; empty means no output); a non-zero exit
-or the per-case `--timeout` (default 600 seconds) is a target failure. The scoped MCP token is
-never logged. The agent key defaults to the slug of the command's script name.
+`--command "<shell command>"` spawns the command once per case with the world's environment
+(`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, one `HUE_SIM_<SURFACE ID>_URL` per provider mirror,
+`HUE_MCP_CONFIG` naming an owner-only `mcpServers` file that is removed after the case, and
+`HUE_MCP_URL`, `HUE_MCP_TOKEN`, `HUE_MCP_EXPIRES_AT` for the first MCP mirror), plus
+`HUE_EXECUTION_ID`, `HUE_ENVIRONMENT_RUN_ID`, `HUE_CASE_ID` and `HUE_CASE_KEY`, and
+`{"inputs": ..., "config": ...}` on stdin. The child does not receive `HUE_API_KEY`, `HUE_MCP_KEY`
+or any other Hue control-plane credential unless `--allow-hue-credentials` is passed; the rest of
+the parent environment (model keys, application settings) is inherited. Its stdout is the answer
+(JSON when it parses, otherwise trimmed text; empty means no output); a non-zero exit or the
+per-case `--timeout` (default 600 seconds) is a target failure. The world token is never logged.
+A world created while the deployment's simulation gateway is off gets the legacy `hue_sim_`
+capability under the same `HUE_MCP_*` names. The agent key defaults to the slug of the command's
+script name; `--revision` is sent to Hue as the agent revision of every world.
 
 `--worker` registers the adapter through `runLocalAgent()` with key `--agent-key` (default: the
 adapter filename slug), name `--agent-name` (default: the key), revision `--revision` (default:
@@ -403,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

@@ -183,7 +183,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
@@ -196,6 +197,67 @@ An observation with `status: "error"` is a recorded world answer, not a transpor
 Run mutations retry with stable invocation/idempotency identities. Registry writes do not retry
 automatically because identity creation and publication have no request key.
 
+## Worlds served by the simulation gateway
+
+Where a Hue deployment has the simulation gateway on, `createRun` returns the World API handoff
+beside the run: `token` (a `hue_world_…` credential that lives exactly as long as the world),
+`surfaces[]` (one mirror URL per pinned provider surface, such as the Gmail MCP and REST mirrors),
+`env` (`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `BAGGAGE`, `TRACEPARENT` and one
+`HUE_SIM_<SURFACE ID>_URL` per surface) and `mcpConfig` (the common `mcpServers` shape with the
+token in the `Authorization` header). The agent is pointed at the mirrors by configuration only:
+its own Gmail MCP or REST client, the mirror URL, the world token where the Google credential went.
+
+```ts
+import {
+  agentEnvironment,
+  createEnvironmentClient,
+  worldHandoff,
+  writeMcpConfig,
+} from "@hue-run/sdk/environment";
+
+const run = await environmentClient.createRun({
+  idempotencyKey: `execution:${executionId}`,
+  environmentVersionId,
+  executionId,
+  ttlSeconds: 600,
+  traceparent: `00-${span.traceId}-${span.spanId}-01`, // parents the world span on the case span
+  agentRevision: "my-agent@1.4.2", // joins the world's fingerprint
+});
+const world = worldHandoff(run); // null for a world created while the gateway is off
+const child = agentEnvironment(world!, { parent: process.env }); // no HUE_API_KEY in the agent
+const config = await writeMcpConfig(world!); // owner-only mcp.json; dispose after the run
+try {
+  await spawnAgent({ env: child, mcpConfigPath: config.path });
+} finally {
+  await config.dispose();
+  await environmentClient.finishRun(run.id, {
+    idempotencyKey: `execution:${executionId}:completed`,
+    status: "completed",
+  });
+}
+```
+
+`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
+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`.
+
+`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.
+Nothing in these helpers logs the token; keep it out of your own logs and checkpoints.
+
+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
+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.
+
 ## Coverage gaps
 
 A provider adapter can record a known valid provider request that the environment cannot

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.
@@ -358,13 +459,28 @@ tick, the transport queues a placeholder: an ordinary OTLP span whose parent is
 with its name, kind, start time and current attributes, an end time of 0,
 `hue.span_type = "pending_span"` and `hue.pending_parent_id` (the running span's own parent,
 omitted for a root). Hue shows the span as running and replaces the placeholder when the real span
-arrives. A placeholder whose span has ended by the time it is exported is not sent.
+arrives.
+
+The placeholder then waits for the next batch export like any queued span: up to 500 ms until the
+next tick, then the 1 s batch delay when nothing else is queued, so it usually reaches Hue within
+about 1.5 s of its span starting. It goes out sooner when a batch is already scheduled, for example
+because another span has just ended, and at once for a full batch or `flush()`. It goes out later
+while an earlier export is still in flight, because the next batch is scheduled only after that
+export finishes. A placeholder whose span has ended by the time it is exported is not sent, so a
+short span may send none and appear in Hue only when it finishes.
 
 - Only spans from the client's tracer (`withSpan`, `tool`, `model`, `hue.tracer` and the AI SDK
   adapters) and spans with a `gen_ai.`, `ai.`, `llm.` or `traceloop.` attribute at start, or a
   name starting with `ai.`, are announced. HTTP, database and other framework spans are not.
 - Placeholder attributes follow `captureContent` and `redact` like the real span. Tool
   definitions, system instructions and any value over 64 KiB are left out.
+- The transport builds each placeholder from the running span itself, so code in a wrapping
+  processor's `onEnd` never runs on it. If a wrapper forwards `onStart` to Hue but scrubs
+  attributes, renames the span or drops it in `onEnd`, a placeholder exported while the span is
+  still open is sent anyway: it has the span's original name, and its attributes as set on the span
+  with `captureContent` and `redact` applied. Scrub with `redact`, which applies to placeholders
+  too, or before the value is set on the span; do not forward `onStart` for spans you rename or
+  drop; or turn live spans off with `liveSpans: false`.
 - Placeholders are advisory. They are queued only while the queue is under a quarter of its
   record and byte budgets, and skipped silently otherwise. While queued they count in
   `pendingSpans` and `pendingBytes`, but never as accepted, rejected, failed or dropped records.

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;
+}