@hue-run/sdk 0.7.0 → 0.8.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.7.0`, `@opentelemetry/api@1.9.1` and
+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.
 
@@ -301,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.7.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
@@ -312,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.7.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
@@ -346,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.
@@ -386,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

@@ -358,13 +358,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/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/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) {