@hue-run/sdk 0.6.0 → 0.8.0

package/CLI.md

@@ -42,8 +42,8 @@ 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.6.0`, `@opentelemetry/api@1.9.1` and
-`@opentelemetry/context-async-hooks@2.11.0`; Python uses published `hue-run==0.2.2`.
+not a completed integration. TypeScript uses `@hue-run/sdk@0.8.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.
 
 The generated bootstrap supplies standard active SERVER-span context across asynchronous/streaming
@@ -231,7 +231,8 @@ capability `setup_telemetry_write`.
 Normal project credentials and unknown token shapes are refused in setup responses and private
 managed state. These credentials authorize metadata-only OTLP at `/api/v1/otlp/v1/traces` and exact
 content-free receipt verification at `/api/v1/setup/traces/{traceId}/receipt`. They do not authorize
-generic project, receipt, evaluation, log or browsing APIs. Published Python `0.2.2` can export with the setup
+generic project, receipt, evaluation, log or browsing APIs. The Python package version
+pinned by setup can export with the setup
 credential; the CLI verifies the dedicated setup receipt instead of Python's generic receipt helper.
 
 Each command uses bounded timeouts and retries. Provisioning records at most five attempts per local
@@ -300,7 +301,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.6.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.8.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -311,7 +312,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.6.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.8.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -345,8 +346,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.
@@ -385,12 +387,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:

package/ENVIRONMENTS.md

@@ -196,6 +196,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

@@ -329,7 +329,8 @@ const hue = createHue({
 
 ## Delivery behavior
 
-Exports use official OTel retry handling for temporary HTTP/network failures. Each
+Exports retry temporary HTTP/network failures (429, 502, 503, 504 and connection errors,
+honoring `Retry-After`) within the export timeout, by OpenTelemetry's OTLP/HTTP exporter rules. Each
 request is limited to 1 MiB before gzip (with space reserved for gzip overhead) and each content value to 256 KiB. Batches
 split at record boundaries. Each signal queues at most 2,048 records, including
 exports in flight; overflow is reported through the callback, counters and next
@@ -349,6 +350,51 @@ drain, including records emitted before its call. Stop request production
 before shutdown so late spans cannot race it. A client does not own instrumented
 operations still running in the application.
 
+## Live spans
+
+OpenTelemetry exports a span only when it ends, so a long streamed turn would otherwise stay
+invisible until it finishes. When a Hue or AI span is still open at the transport's next 500 ms
+tick, the transport queues a placeholder: an ordinary OTLP span whose parent is the running span,
+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.
+
+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.
+  Losing only placeholders records a warning and does not make `flush()` throw.
+- A Hue server that accepts placeholders sends `Hue-Pending-Spans: 1` on trace acknowledgements.
+  When a response to a request carrying placeholders lacks it, the receiver predates them: the
+  transport attributes up to one rejection per placeholder to them, records one warning and stops
+  sending placeholders for that client. Other rejections count against real spans as usual.
+- Opt out with `liveSpans: false`. Setup credentials never send placeholders.
+- With an existing provider, announcements start in `spanProcessor.onStart`. A wrapping processor
+  that forwards `onStart` should forward `onEnd` for the same spans: a span that ends without
+  reaching Hue is forgotten at the next tick, but a placeholder already sent keeps it showing as
+  running until Hue marks the trace stalled. The filtering wrapper above forwards no starts, so it
+  sends no placeholders.
+
 ## Verify a stored application trace
 
 After exercising a real application request and finishing its stream, flush the

package/dist/cli/eval.js

@@ -6,6 +6,7 @@ import { parseArgs } from "node:util";
 import { randomUUID } from "node:crypto";
 import { createHue } from "../client.js";
 import { createEnvironmentClient } from "../environment/client.js";
+import { agentEnvironment, stripHueControlPlaneCredentials, writeMcpConfig, } from "../environment/world.js";
 import { EvaluationClient, HueApiError } from "../evals/client.js";
 import { TargetResult } from "../evals/types.js";
 import { CheckpointStore } from "../evals/checkpoint.js";
@@ -32,9 +33,15 @@ Selection (exactly one, not used with --worker):
 
 Agent (exactly one):
   <adapter-file>                  Module exporting default or runMyAgent(inputs, context)
-  --command "<shell command>"     Simulation: spawned 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 set; {"inputs","config"} on stdin.
+  --command "<shell command>"     Simulation: spawned per case with the world's environment
+                                  (HUE_WORLD_ID, HUE_WORLD_TOKEN, one HUE_SIM_<SURFACE>_URL per
+                                  provider mirror, HUE_MCP_CONFIG, plus HUE_MCP_URL, HUE_MCP_TOKEN
+                                  and HUE_MCP_EXPIRES_AT for the first MCP mirror), HUE_EXECUTION_ID,
+                                  HUE_ENVIRONMENT_RUN_ID, HUE_CASE_ID and HUE_CASE_KEY set;
+                                  {"inputs","config"} on stdin. HUE_API_KEY and other Hue
+                                  control-plane credentials are removed from the child.
+  --allow-hue-credentials         Keep HUE_API_KEY and other Hue control-plane credentials in
+                                  the --command child (off by default)
                                   Direct: spawned in a private case directory with HUE_CASE_DIR,
                                   HUE_CASE_INPUTS, HUE_CASE_OUTPUT_DIR, HUE_CASE_ID, HUE_CASE_KEY
                                   and HUE_EXECUTION_ID set; files/<role>/ hold the pinned inputs
@@ -59,7 +66,7 @@ Output and limits:
                                   outputs/explanations (--worker always persists them)
   --save-version                  Freeze an unsaved eval-set version before running
   --checkpoint-dir <path>         Private checkpoint directory (default: .hue/eval/<agent-key>)
-  --concurrency <n>               Cases in flight, 1-16 (default: 1)
+  --concurrency <n>               Cases in flight, 1-64 (default: 1)
   --timeout <seconds>             Per-case --command timeout (default: 600)
   --wait <seconds>                Verdict wait after the run finishes (default: 300)
   -h, --help                      Show this help
@@ -92,6 +99,7 @@ function parse(argv) {
                 "scorer-version": { type: "string", multiple: true },
                 mode: { type: "string" },
                 command: { type: "string" },
+                "allow-hue-credentials": { type: "boolean", default: false },
                 worker: { type: "boolean", default: false },
                 "max-runs": { type: "string" },
                 "agent-key": { type: "string" },
@@ -296,29 +304,65 @@ function parseAnswer(text) {
         return text;
     }
 }
-/** Runs the shell command once per case; the MCP token travels only through the child's environment. */
-function commandAdapter(command, timeoutSeconds) {
-    return async (inputs, context) => parseAnswer(await spawnAgentCommand(command, {
-        env: {
-            ...process.env,
-            HUE_MCP_URL: context.mcp.url,
-            HUE_MCP_TOKEN: context.mcp.token,
-            HUE_MCP_EXPIRES_AT: context.mcp.expiresAt,
+/**
+ * Runs the shell command once per case. The world token and mirror URLs travel only through the
+ * child's environment and an owner-only MCP configuration file that is removed after the run;
+ * Hue control-plane credentials (`HUE_API_KEY`, `HUE_MCP_KEY`, any `hue_sk_` value) stay with
+ * the CLI unless `--allow-hue-credentials` is passed. A world created while the gateway is off
+ * still gets the `hue_sim_` capability under the same `HUE_MCP_*` names.
+ */
+/** The parent environment an agent child starts from: without Hue control-plane credentials
+ * unless `--allow-hue-credentials` was passed. */
+function parentEnvironment(allowHueCredentials) {
+    return allowHueCredentials
+        ? Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined))
+        : stripHueControlPlaneCredentials(process.env);
+}
+function commandAdapter(command, timeoutSeconds, options) {
+    return async (inputs, context) => {
+        const parent = parentEnvironment(options.allowHueCredentials);
+        const identity = {
             HUE_EXECUTION_ID: context.executionId,
             HUE_ENVIRONMENT_RUN_ID: context.environmentRunId,
             HUE_CASE_ID: context.item.id,
             HUE_CASE_KEY: context.item.externalKey,
-        },
-        stdin: JSON.stringify({ inputs, config: context.config }),
-        timeoutSeconds,
-        ...(context.signal ? { signal: context.signal } : {}),
-    }));
+        };
+        const configFile = context.world ? await writeMcpConfig(context.world) : undefined;
+        try {
+            const env = context.world
+                ? {
+                    ...agentEnvironment(context.world, { parent, includeHueCredentials: true }),
+                    ...identity,
+                    HUE_MCP_CONFIG: configFile.path,
+                }
+                : {
+                    ...parent,
+                    ...(context.mcp
+                        ? {
+                            HUE_MCP_URL: context.mcp.url,
+                            HUE_MCP_TOKEN: context.mcp.token,
+                            HUE_MCP_EXPIRES_AT: context.mcp.expiresAt,
+                        }
+                        : {}),
+                    ...identity,
+                };
+            return parseAnswer(await spawnAgentCommand(command, {
+                env,
+                stdin: JSON.stringify({ inputs, config: context.config }),
+                timeoutSeconds,
+                ...(context.signal ? { signal: context.signal } : {}),
+            }));
+        }
+        finally {
+            await configFile?.dispose();
+        }
+    };
 }
 /**
  * Direct cases: the command works in a private case directory and writes its documents to
  * `output/`. Its stdout is only used as the JSON output when it wrote no result or summary file.
  */
-function directCommandAdapter(command, timeoutSeconds) {
+function directCommandAdapter(command, timeoutSeconds, options) {
     return async (inputs, context) => {
         const layout = await stageDirectCase(context.outputDirectory, {
             inputs,
@@ -330,7 +374,7 @@ function directCommandAdapter(command, timeoutSeconds) {
         const stdout = await spawnAgentCommand(command, {
             cwd: layout.caseDirectory,
             env: {
-                ...process.env,
+                ...parentEnvironment(options.allowHueCredentials),
                 HUE_CASE_DIR: layout.caseDirectory,
                 HUE_CASE_INPUTS: layout.inputsPath,
                 HUE_CASE_OUTPUT_DIR: layout.outputDirectory,
@@ -636,7 +680,7 @@ function parseBaseline(value) {
 }
 async function runOnce(values, connection, agents, agent, hue, output, signal) {
     const client = new EvaluationClient(connection);
-    const concurrency = integer("concurrency", values.concurrency, 1, 1, 16);
+    const concurrency = integer("concurrency", values.concurrency, 1, 1, 64);
     const baselineId = parseBaseline(values.baseline);
     const mode = parseMode(values.mode);
     const pins = await resolveSelection(client, values);
@@ -683,6 +727,10 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
         persistResultContent: values.content,
         traceEvidence: { mode: "required" },
         concurrency,
+        agentRevision: agent.revision,
+        // The CLI adapts to whatever the deployment serves; the library warning is for code that
+        // still reads the legacy capability itself.
+        deprecationWarnings: false,
         signal,
         target: agents.simulation,
         async onProgress(event) {
@@ -820,7 +868,7 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
     const client = new ObservedClient(connection);
     const environmentClient = createEnvironmentClient(connection);
     const wait = integer("wait", values.wait, 300, 0, 86_400);
-    const concurrency = integer("concurrency", values.concurrency, 1, 1, 16);
+    const concurrency = integer("concurrency", values.concurrency, 1, 1, 64);
     const maxRuns = values["max-runs"] === undefined
         ? undefined
         : integer("max-runs", values["max-runs"], 1, 1, 1_000_000);
@@ -847,6 +895,7 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
         },
         scorers: [],
         concurrency,
+        deprecationWarnings: false,
         signal,
         ...(maxRuns === undefined ? {} : { maxRuns }),
         target(inputs, tools, context) {
@@ -857,7 +906,8 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
                 executionId: context.executionId,
                 environmentRunId: context.environmentRunId,
                 tools,
-                mcp: context.mcp,
+                ...(context.world ? { world: context.world } : {}),
+                ...(context.mcp ? { mcp: context.mcp } : {}),
                 ...(context.connectionBundle ? { connectionBundle: context.connectionBundle } : {}),
                 signal,
             });
@@ -959,8 +1009,13 @@ export async function runEvalCommand(argv) {
                         throw new Error("The adapter returned generated files for a simulated-world case");
                     return answer;
                 }
-                : commandAdapter(values.command, timeout),
-            direct: loaded ?? directCommandAdapter(values.command, timeout),
+                : commandAdapter(values.command, timeout, {
+                    allowHueCredentials: values["allow-hue-credentials"],
+                }),
+            direct: loaded ??
+                directCommandAdapter(values.command, timeout, {
+                    allowHueCredentials: values["allow-hue-credentials"],
+                }),
         };
         hue = createHue({ apiKey, baseUrl, serviceName: key, captureContent: values.content });
         return values.worker

package/dist/client.js

@@ -6,6 +6,7 @@ import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { TracerProvider } from "@opentelemetry/sdk-trace";
 import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
+import { HUE_SCOPE } from "./config.js";
 import { encodeContent, noopSpan, safeSpan } from "./safety.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
@@ -197,8 +198,8 @@ export class HueClient {
         }
         this.captureContent = this.transport.options.captureContent;
         this.enabled = this.transport.options.enabled !== false;
-        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
-        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", sdkVersion);
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer(HUE_SCOPE, sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
+        this.logger = this.loggerProvider.getLogger(HUE_SCOPE, sdkVersion);
     }
     /**
      * Verifies that Hue stored a trace by ID, optionally waiting for expected span IDs and normalized

package/dist/config.d.ts

@@ -1,11 +1,13 @@
 import type { HueOptions, SharedHueOptions } from "./types.js";
 export declare const MAX_BODY_BYTES: number;
 export declare const MAX_CONTENT_BYTES: number;
+/** Instrumentation scope of the client's own tracer and logger. */
+export declare const HUE_SCOPE = "@hue-run/sdk";
 /** Loopback hostnames that may use plain HTTP without opting in. */
 export declare function isLoopbackHost(hostname: string): boolean;
 /** True when a validated origin exports over plain HTTP to a host other than loopback. */
 export declare function isInsecureOrigin(baseUrl: string): boolean;
-export declare function validateOptions(options: HueOptions): HueOptions & Required<Pick<SharedHueOptions, "captureContent" | "baseUrl" | "timeoutMillis" | "maxQueueBytes">> & {
+export declare function validateOptions(options: HueOptions): HueOptions & Required<Pick<SharedHueOptions, "captureContent" | "baseUrl" | "timeoutMillis" | "maxQueueBytes" | "liveSpans">> & {
     /** Project key after validation; empty for a disabled client. */
     apiKey: string;
     /** Service name after validation; `hue-disabled` for a disabled client. */

package/dist/config.js

@@ -1,5 +1,7 @@
 export const MAX_BODY_BYTES = 1024 * 1024;
 export const MAX_CONTENT_BYTES = 256 * 1024;
+/** Instrumentation scope of the client's own tracer and logger. */
+export const HUE_SCOPE = "@hue-run/sdk";
 /** Loopback hostnames that may use plain HTTP without opting in. */
 export function isLoopbackHost(hostname) {
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
@@ -30,6 +32,7 @@ export function validateOptions(options) {
             baseUrl: "https://app.hue.run",
             timeoutMillis: 10000,
             maxQueueBytes: 8 * 1024 * 1024,
+            liveSpans: false,
         };
     }
     if (typeof options.captureContent !== "boolean")
@@ -74,5 +77,9 @@ export function validateOptions(options) {
         maxQueueBytes < 1024 ||
         maxQueueBytes > 64 * 1024 * 1024)
         throw new TypeError("maxQueueBytes must be 1024–67108864");
-    return { ...options, baseUrl: url.origin, timeoutMillis, maxQueueBytes };
+    if (options.liveSpans !== undefined && typeof options.liveSpans !== "boolean")
+        throw new TypeError("liveSpans must be a boolean");
+    // Setup credentials send installer telemetry only, never in-progress placeholders.
+    const liveSpans = options.liveSpans !== false && !options.apiKey.startsWith("hue_setup_");
+    return { ...options, baseUrl: url.origin, timeoutMillis, maxQueueBytes, liveSpans };
 }

package/dist/environment/client.d.ts

@@ -1,4 +1,4 @@
-import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, PublishableEnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions } from "./types.js";
+import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, PublishableEnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions, WorldEvidence, WorldEvidenceOptions } from "./types.js";
 /** Connection and retry options for {@link createEnvironmentClient}. */
 export interface EnvironmentClientOptions {
     /** Project service key sent as a bearer token; server-side only. */
@@ -14,9 +14,13 @@ export interface EnvironmentClientOptions {
 export declare class HueEnvironmentError extends Error {
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     readonly status?: number | undefined;
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    readonly retryAfterMs?: number | undefined;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
-    status?: number | undefined);
+    status?: number | undefined, 
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    retryAfterMs?: number | undefined);
 }
 /** Typed client for authored environments, isolated runs and immutable journals. */
 export declare class EnvironmentClient {
@@ -57,6 +61,13 @@ export declare class EnvironmentClient {
         sealedAt: string | null;
         stateDigest: string;
         finalState?: import("./types.js").JsonValue;
+        worldId?: string;
+        lifecycle?: import("./types.js").WorldLifecycle;
+        completingUntil?: string | null;
+        traceExternalId?: string | null;
+        surfaces?: import("./types.js").WorldSurface[];
+        flags?: import("./types.js").WorldFlag[];
+        connection?: null;
         validity: "environment_incomplete" | "not_assessed";
         coverageGap: import("./types.js").CoverageGap | null;
     }>;
@@ -68,6 +79,9 @@ export declare class EnvironmentClient {
     listSteps(runId: string, page?: StepPageOptions): Promise<StepPage>;
     /** Seals a world as completed or abandoned and freezes its evidence. */
     finishRun(runId: string, input: FinishRunInput): Promise<SealedRun>;
+    /** Reads a sealed world's evaluator-only evidence with the project key; a world token never
+     * can. An open world answers 409 until it is sealed. */
+    getEvidence(runId: string, options?: WorldEvidenceOptions): Promise<WorldEvidence>;
 }
 /** Creates a typed simulated-environment client. */
 export declare function createEnvironmentClient(options: EnvironmentClientOptions): EnvironmentClient;

package/dist/environment/client.js

@@ -3,17 +3,38 @@ import { aggregateBounds, json, uuid, valueBounds } from "../evals/json.js";
 /** Sanitized environment API failure that never includes response text or credentials. */
 export class HueEnvironmentError extends Error {
     status;
+    retryAfterMs;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
-    status) {
+    status, 
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    retryAfterMs) {
         super(status
             ? `Hue environment request failed (HTTP ${status})`
             : "Hue environment connection or response failed");
         this.status = status;
+        this.retryAfterMs = retryAfterMs;
         this.name = "HueEnvironmentError";
     }
 }
 const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+/** A `Retry-After` longer than this waits this long: Hue asks for a second, never minutes. */
+const MAX_RETRY_AFTER_MS = 10_000;
+const TRACEPARENT = /^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+/** Version 00 with real identifiers: an all-zero trace or span ID is invalid, and Hue refuses it. */
+function validTraceparent(value) {
+    if (!TRACEPARENT.test(value))
+        return false;
+    const [, traceId, spanId] = value.split("-");
+    return !/^0+$/.test(traceId) && !/^0+$/.test(spanId);
+}
+/** Whole seconds only, as Hue sends them; a date or garbage is ignored. */
+function retryAfterMillis(response) {
+    const header = response.headers.get("retry-after");
+    if (header === null || !/^\d{1,6}$/.test(header.trim()))
+        return undefined;
+    return Math.min(Number(header.trim()) * 1000, MAX_RETRY_AFTER_MS);
+}
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 const REQUEST_BOUNDS = { ...valueBounds, bytes: 1024 * 1024 };
 /** The server bounds JSON inside each entity independently, then permits the parsed
@@ -62,7 +83,7 @@ export class EnvironmentClient {
         }
         if (!response.ok) {
             await response.body?.cancel();
-            throw new HueEnvironmentError(response.status);
+            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined);
         }
         try {
             const reader = response.body?.getReader();
@@ -105,8 +126,10 @@ export class EnvironmentClient {
                 const recoverable = error.status === undefined || RETRYABLE.has(error.status);
                 if (!recoverable || attempt >= this.maxAttempts)
                     throw error;
+                // Hue's admission refusals say how long to wait; anything else backs off.
                 const backoff = Math.min(100 * 2 ** (attempt - 1), 2000);
-                await new Promise((resolve) => setTimeout(resolve, backoff + Math.random() * backoff));
+                const wait = error.retryAfterMs ?? backoff + Math.random() * backoff;
+                await new Promise((resolve) => setTimeout(resolve, wait));
             }
         }
     }
@@ -157,6 +180,13 @@ export class EnvironmentClient {
             throw new RangeError("ttlSeconds must be 1–86400");
         if (input.seed !== undefined && !/^[a-f0-9]{32}$/.test(input.seed))
             throw new TypeError("Seed must be 32 lowercase hexadecimal characters");
+        if (input.traceparent !== undefined && !validTraceparent(input.traceparent))
+            throw new TypeError("traceparent must be a version-00 W3C trace context");
+        if (input.agentRevision !== undefined &&
+            (typeof input.agentRevision !== "string" ||
+                input.agentRevision.length < 1 ||
+                input.agentRevision.length > 256))
+            throw new RangeError("agentRevision must be 1–256 characters");
         return this.request("POST", "/environment-runs", {
             ...input,
             environmentVersionId: uuid(input.environmentVersionId),
@@ -202,6 +232,19 @@ export class EnvironmentClient {
     finishRun(runId, input) {
         return this.request("POST", `/environment-runs/${uuid(runId)}/finish`, input);
     }
+    /** Reads a sealed world's evaluator-only evidence with the project key; a world token never
+     * can. An open world answers 409 until it is sealed. */
+    getEvidence(runId, options = {}) {
+        const query = new URLSearchParams();
+        if (options.section !== undefined) {
+            if (!["all", "start", "end", "diff", "ledger"].includes(options.section))
+                throw new TypeError("Evidence section must be all, start, end, diff or ledger");
+            query.set("section", options.section);
+        }
+        if (options.bodies !== undefined)
+            query.set("bodies", options.bodies ? "true" : "false");
+        return this.request("GET", `/environment-runs/${uuid(runId)}/evidence${query.size ? `?${query}` : ""}`);
+    }
 }
 /** Creates a typed simulated-environment client. */
 export function createEnvironmentClient(options) {