@hue-run/sdk 0.12.1 → 0.13.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.12.1`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.13.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.
 
@@ -469,7 +469,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.12.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -480,7 +480,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.12.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -512,12 +512,38 @@ the sealed world. Hue never executes the agent. `HUE_API_KEY` must be a **Read a
 write** project key (a **Read** or **Tracing only** key cannot read cases or create runs);
 the CLI never prints it. The optional `zod` peer of `@hue-run/sdk/evals` must be installed.
 
-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` (`world`, `mcp`, `tools`, `config`, `item`, `executionId`,
-`environmentRunId`, `files`, `outputDirectory`, `signal`; `world` carries the provider mirror URLs,
-the world token, `env` and `mcpConfig` where Hue's simulation gateway serves the world). When the
-case also pins input files, `files` holds verified copies of its agent-visible ones (see
+Run the agent's own start command with `--command`. `hue eval` spawns it once per case with the
+world's environment (below) and `{"inputs", "config"}` on stdin, and stores its stdout as the
+answer. The agent reaches each app through Hue's mirror with its own production client: the one
+committed helper described in [Make your agent eval-ready](https://docs.hue.run/evaluations/eval-ready-agent)
+reads `HUE_SIM_<SURFACE ID>_URL` and `HUE_WORLD_TOKEN` when `HUE_WORLD_TOKEN` is set, fails
+closed when a needed variable is missing, and returns the production URL and credential
+otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`) or a tool its
+production agent lacks. Pin the SDK and bring its `zod` peer along, so the agent's repository
+gains no dependency:
+
+```sh
+npx --yes --package @hue-run/sdk@0.13.1 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" --command "node agent.js" --env-file .env.hue
+npx --yes --package @hue-run/sdk@0.13.1 --package "zod@^4.6.5" hue eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <experiment id>
+npx --yes --package @hue-run/sdk@0.13.1 --package "zod@^4.6.5" hue eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx --yes --package @hue-run/sdk@0.13.1 --package "zod@^4.6.5" hue eval --worker --command "node agent.js" --agent-key support-agent --env-file .env.hue
+```
+
+Without the second `--package`, `hue eval` exits with `hue eval needs zod`, even for `--help`;
+installing zod in the project does not help when the SDK itself is not installed there. An
+unpinned `--package @hue-run/sdk` runs a local, possibly older, copy in a project that already
+depends on it.
+
+An adapter module is the in-process alternative for a TypeScript agent. It exports `default` or
+`runMyAgent`; `context` is the SDK's `SimulationTargetContext` (`world`, `mcp`, `tools`, `config`,
+`item`, `executionId`, `environmentRunId`, `files`, `outputDirectory`, `signal`; `world` carries
+the provider mirror URLs, the world token, `env` and `mcpConfig` where Hue's simulation gateway
+serves the world). An adapter runs inside `hue eval`'s own process, where `HUE_WORLD_TOKEN` and
+`HUE_EXECUTION_ID` are not set, so a helper that reads the process environment would return
+production values: throw when `context.world` is missing, then pass `context.world.env` as the
+helper's environment argument or spawn the agent with `agentEnvironment(context.world)`. Never
+set `process.env` yourself; with `--concurrency` above 1 that leaks one case's world into another.
+When the case also pins input files, `files` holds verified copies of its agent-visible ones (see
 [Evaluate a document eval set](#evaluate-a-document-eval-set)); return
 `withFiles(output, files)` from `@hue-run/sdk/evals` to upload documents the agent produced:
 
@@ -527,19 +553,16 @@ import type { JsonValue, SimulationTargetContext } from "@hue-run/sdk/evals";
 import { runAgent } from "./src/agent.js"; // The application's existing entry point.
 
 export default function runMyAgent(inputs: JsonValue, context: SimulationTargetContext) {
-  // Hand context.tools or context.mcp to the agent's real tool boundary; configuration alone
-  // does not redirect provider calls. Pass context.signal for cooperative cancellation.
-  const { config, tools, mcp, signal } = context;
-  return runAgent({ inputs, config, tools, mcp, signal });
+  if (!context.world) throw new Error("This case has no world handoff; refusing to run against the real app");
+  // The agent's own app clients read the mirrors through the committed helper, given the
+  // world's environment; never hand it context.tools or context.mcp. Pass context.signal for
+  // cooperative cancellation.
+  return runAgent({ inputs, config: context.config, env: context.world.env, signal: context.signal });
 }
 ```
 
 ```sh
-hue eval --case "Refund an eligible charge" ./hue-agent.ts --content --env-file .env.hue
-hue eval --case https://app.hue.run/projects/demo/scenarios/<id> ./hue-agent.ts --content --baseline <run id>
-hue eval --set "Billing regressions" --scorer-version <id> ./hue-agent.ts --content --save-version
-hue eval --case "Refund an eligible charge" --command "python agent.py" --timeout 120 --content
-hue eval --worker ./hue-agent.ts --agent-key support-agent --content --env-file .env.hue
+npx --yes --package @hue-run/sdk@0.13.1 --package "zod@^4.6.5" hue eval --case "Refund an eligible charge" ./hue-agent.ts --content --env-file .env.hue
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -576,7 +599,9 @@ Hue-owned `world_outcome` checks are graded after the world seals. An experiment
 every case of the saved version; there is no case subset.
 
 `--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_WORLD_ID`, `HUE_WORLD_TOKEN`, `HUE_WORLD_NOW` (the world's clock at creation, RFC 3339; `worldNow()` reads it and returns
+`null` without it, so fall back explicitly with `worldNow() ?? new Date()`), 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; these name the
 world's simulated MCP server and replace a `HUE_MCP_URL` that `hue login` stored for Hue's project

package/ENVIRONMENTS.md

@@ -220,10 +220,24 @@ automatically because identity creation and publication have no request key.
 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.
+`now` (the world's clock at creation as an RFC 3339 timestamp), `env` (`HUE_WORLD_ID`,
+`HUE_WORLD_TOKEN`, `HUE_WORLD_NOW`, `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.
+
+The world has its own date. A trace-built world's clock is frozen at the recorded start, so a
+run that begins days or months after the recording still finds the recorded emails, events and
+records at their recorded times. An agent that reads the wall clock for "today", "tomorrow" or
+`newer_than:7d` asks the world about dates it holds nothing for; one that reads the world's date
+lands on the recorded ones. Read it with `worldNow`: from the handoff, or from the environment of
+an agent child, where `agentEnvironment` and `hue eval --command` set `HUE_WORLD_NOW`.
+
+```ts
+import { worldNow } from "@hue-run/sdk/environment";
+
+const today = worldNow() ?? new Date(); // HUE_WORLD_NOW in this process, else the wall clock
+```
 
 ```ts
 import {
@@ -314,8 +328,11 @@ type; see [EVALUATIONS.md](EVALUATIONS.md#direct-cases-and-files).
 A refusal such as 409 `simulation_gateway_required` exposes its validated server code as `HueEnvironmentError.diagnostic`.
 
 `agentEnvironment` removes Hue control-plane credentials from the child by default: `HUE_API_KEY`,
-`HUE_MCP_KEY` and any variable whose value is a `hue_sk_`, `hue_mcp_` or `hue_attempt_`
-credential. Pass `includeHueCredentials: true` only for an agent that must call Hue's own API.
+`HUE_MCP_KEY`, and any value carrying a Hue control-plane credential (`hue_sk_`, `hue_setup_`,
+`hue_attempt_`, `hue_mcp_`, `hue_inv_`, `hue_install_`, `hue_at_`, `hue_rt_`, `hue_oauth_`)
+anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. World tokens and
+`hue_sim_` capabilities pass. 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

package/EVALUATIONS.md

@@ -107,6 +107,24 @@ evidence and scoring while retaining this runner's checkpoint guarantees. See
 Cases whose inputs are a task plus pinned documents, and rescoring over documents a run already
 saved, use the same runner without a world. See [Direct cases and files](#direct-cases-and-files).
 
+## Tags
+
+Tags group datasets, scorers and experiments, for example by the area of the agent they test.
+Methods take tag names: a name the project has no tag for creates one, and names match without
+case. `createDataset`, `createScorer` and `createExperiment` accept `tags`; `updateDataset`,
+`updateScorer` and `updateExperiment` replace an item's tags; `listDatasets` and `listScorers`
+filter by `tags`, matching any of them; and `listTags()` returns the project's tags. An experiment
+also shows its dataset's tags, which experiment filters match as well. The product-named methods
+(`createEvalSet`, `updateEvalSet`, `listEvalSets`, `createEvaluator`, `updateEvaluator`,
+`listEvaluators`, `createRun`, `updateRun`) take the same `tags`. Tags require a Hue server that
+supports them.
+
+```ts
+await client.createEvalSet({ name: "Refunds", slug: "refunds", tags: ["billing"] });
+await client.updateEvaluator(evaluatorId, { tags: ["billing", "regression"] });
+const billing = await client.listEvalSets({ tags: ["billing"] });
+```
+
 ## Content and result states
 
 Both choices are required and independent:
@@ -146,7 +164,7 @@ A callback receives `{inputs,hasOutput,output?,hasExpected,expected?,metadata,ex
 - `{state:"error",error:{type,message?}}`.
 - `{state:"skipped",explanation:"reason"}`.
 
-All declared metrics must appear exactly once and satisfy pinned types, bounds and categories. The binding must match language, entrypoint, SHA-256 source digest and metric definitions. The digest is an authenticated caller declaration; it does not attest closures, dependency versions or actual execution. Callback source is never downloaded or evaluated. Callbacks are trusted local code; they have **no execution timeout or side-effect cancellation**. Concurrency limits active cases to 1–16 (default 1), with scorers evaluated sequentially within each case.
+All declared metrics must appear exactly once and satisfy pinned types, bounds and categories. Each metric may include an optional `description` (1–500 characters) shown with its check in Hue's run view. The binding must match language, entrypoint, SHA-256 source digest and metric definitions. The digest is an authenticated caller declaration; it does not attest closures, dependency versions or actual execution. Callback source is never downloaded or evaluated. Callbacks are trusted local code; they have **no execution timeout or side-effect cancellation**. Concurrency limits active cases to 1–16 (default 1), with scorers evaluated sequentially within each case.
 
 `files` is present only when the runner handled files for that execution: every pinned input file
 (all roles, including the evaluator-only `org_template`) and every generated output, each with its

package/README.md

@@ -45,7 +45,6 @@ await hue.withSpan(
   async (span) => {
     const output = await hue.tool("uppercase", "hello", () => "hello".toUpperCase());
     span.setOutput(output);
-    hue.recordMessages({ output: [{ role: "assistant", content: output }] });
   },
   { sessionId: "session-123", userId: "user-123", input: "hello" },
 );
@@ -107,7 +106,8 @@ by the semantic conventions'
 [input messages](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.0/docs/gen-ai/gen-ai-input-messages.json)
 and
 [output messages](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.0/docs/gen-ai/gen-ai-output-messages.json)
-JSON schemas, so any semantic-convention-aware backend can read them. Convert provider-native
+JSON schemas. GenAI conventions are in Development; Hue supports the fields described here
+and accepts caller-supplied JSON without validating the full draft. Convert provider-native
 messages before recording them:
 
 ```ts
@@ -313,7 +313,7 @@ policy forbids sending that content to another service. `redact` and the credent
 described below apply in both modes.
 
 `captureContent: false` disables manual input/output/messages/tool content and
-removes recognized GenAI, Vercel, OpenInference and OpenLLMetry content attributes,
+removes recognized GenAI, Vercel, OpenInference, OpenLLMetry and Langfuse content attributes,
 legacy GenAI content events, log bodies, status messages and exception text before
 export. The exported `contentPrefixes` array lists the attribute keys (and their dotted
 children) that are removed. Model/provider/token metadata remains available. Generic custom attribute
@@ -323,7 +323,13 @@ names cannot be classified automatically; use them deliberately.
 there is no SDK retention timer or automatic content expiry. To redact strings
 before export, supply `redact(value, path)`; it applies to supported strings in
 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
+Invalid helper content is omitted with an instrumentation failure; the span can still be delivered.
+A content value over Hue's 256 KiB value cap is not omitted: text is cut to a UTF-8 prefix and
+bytes or a structured log body are replaced by the receiver's own marker
+(`{ "hue.truncated": true, "hue.truncated_bytes": <size> }`), and the value's key is listed in
+the record's `hue.truncated` attribute, where Hue's receiver lists the values it cuts itself,
+so the span still carries the call, the recorded part of its value and the rest of its evidence.
+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
@@ -355,7 +361,7 @@ rotates. Only definitions another integration recorded can be summarized: `hueTe
 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 when a
+parts in `ai.prompt.messages`. A span whose messages exceed 256 KiB would be cut, so when a
 record is queued Hue replaces the `content`/`data` of any such part longer than 64 KiB with the
 file's `sha256` and `size`, both of the file's own bytes whatever its media type (base64 content
 and `;base64` `data:` URLs decoded, other `data:` URLs percent-decoded, anything else as UTF-8 text), keeping the part's other fields such as `type`, `mime_type` and `mediaType`. Smaller inline
@@ -379,8 +385,8 @@ span in `finally`.
 the active span, with the messages in its body. The record also carries `gen_ai.operation.name`,
 `gen_ai.provider.name` and `gen_ai.request.model` as attributes, copied from the enclosing
 `hue.model()` span or passed as `operation`, `provider` and `model`, and `gen_ai.conversation.id`
-from the active session, so a collector fan-out to another GenAI-aware backend keeps the request
-context.
+from the active session, when those values are known. Use `recordMessages` inside `hue.model()` or
+supply `operation` and `provider` explicitly to include the required inference context.
 
 ## Existing OpenTelemetry providers
 
@@ -447,7 +453,8 @@ that accepts `/api/v1/otlp/v1/traces` and `/api/v1/otlp/v1/logs` (for example an
 Collector `otlp` receiver with `http.traces_url_path` and `logs_url_path` set to those paths,
 forwarding to Jaeger or the debug exporter) and pass any placeholder `apiKey`; HTTP is allowed
 for loopback origins. `checkConnection()` and `verifyTrace()` are Hue-only diagnostics and are
-not available against a generic collector.
+not available against a generic collector. Set `liveSpans: false` so Hue-specific placeholders
+do not reach the collector's other destinations.
 
 A collector on a private network is not loopback: a docker-compose sibling such as
 `http://otel-collector:4318` or an in-cluster service requires the explicit opt-in
@@ -461,6 +468,7 @@ const hue = createHue({
   serviceName: "my-agent",
   captureContent: true,
   baseUrl: "http://otel-collector:4318",
+  liveSpans: false,
   allowInsecureHttp: true,
 });
 ```
@@ -470,7 +478,11 @@ const hue = createHue({
 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
+split at record boundaries. A record over the request limit on its own sheds its content values,
+largest first, each replaced by the receiver's marker and listed under `hue.truncated`, until it
+fits; only a record too large without any content value is lost, reported as an `invalid` issue,
+and counted on its trace's root span as `hue.sdk.dropped_records` when the root is exported, so
+Hue reads the trace as incomplete by that many records. Each signal queues at most 2,048 records, including
 exports in flight; overflow is reported through the callback, counters and next
 flush. This is an in-memory queue, not durable storage.
 
@@ -522,10 +534,14 @@ short span may send none and appear in Hue only when it finishes.
   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.
+- Placeholders travel in their own requests, after an export's completed spans, so a rejection
+  count is always one kind of record's: a completed span's rejection is never credited to a
+  placeholder, and a rejected request of placeholders is a warning. A Hue server that accepts
+  placeholders sends `Hue-Pending-Spans: 1` on every trace acknowledgement. The first trace
+  acknowledgement without it, whatever its request carried, shows the receiver predates them: the
+  transport records one warning (counting the placeholders the receiver rejected in that request, if any) and stops
+  sending placeholders for that client, so a receiver that acknowledged completed spans first
+  never receives one.
 - 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

package/dist/client.d.ts

@@ -154,6 +154,14 @@ export declare class HueClient {
      * alone is omitted and counted while the rest is recorded.
      */
     recordFile(file: FileRecord, explicitContext?: Context): void;
+    /** The keys of each span's content values that were cut to Hue's value cap, for `hue.truncated`. */
+    private truncatedKeys;
+    /**
+     * A content value as a JSON attribute within Hue's 256 KiB value cap. A larger value is cut to
+     * a UTF-8 prefix and its key listed under `hue.truncated`, where Hue's receiver lists the
+     * values it cuts itself: the span carries the call and the recorded part of its value instead
+     * of losing the value whole. Only a value that cannot be encoded is omitted and counted.
+     */
     private setContent;
     /**
      * Confirms the key and origin by reading the current project; a setup and CI diagnostic, not a

package/dist/client.js

@@ -10,7 +10,8 @@ import { defaultResource, resourceFromAttributes } from "@opentelemetry/resource
 import { HUE_SCOPE } from "./config.js";
 import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, providerErrorDescription, } from "./provider-tools.js";
 import { toolCatalogSummary } from "./tool-definitions.js";
-import { encodeContent, noopSpan, safeSpan } from "./safety.js";
+import { encodeBoundedContent, encodeContent, noopSpan, safeSpan, } from "./safety.js";
+import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
@@ -712,11 +713,31 @@ export class HueClient {
             this.instrumentationFailed();
         }
     }
+    /** The keys of each span's content values that were cut to Hue's value cap, for `hue.truncated`. */
+    truncatedKeys = new WeakMap();
+    /**
+     * A content value as a JSON attribute within Hue's 256 KiB value cap. A larger value is cut to
+     * a UTF-8 prefix and its key listed under `hue.truncated`, where Hue's receiver lists the
+     * values it cuts itself: the span carries the call and the recorded part of its value instead
+     * of losing the value whole. Only a value that cannot be encoded is omitted and counted.
+     */
     setContent(span, key, value) {
         if (!this.enabled || this.closed || !this.captureContent)
             return;
         try {
-            span.setAttribute(key, encodeContent(value));
+            const { text, truncated } = encodeBoundedContent(value);
+            span.setAttribute(key, text);
+            // The span's list as it stands: the application's own entries (read from the SDK span,
+            // which carries its attributes; the API alone shows none) and this helper's earlier ones.
+            const listed = withTruncatedKeys(span.attributes?.[TRUNCATED_KEY], this.truncatedKeys.get(span) ?? []);
+            const keys = truncated
+                ? withTruncatedKeys(listed, [key])
+                : listed.filter((entry) => entry !== key);
+            if (truncated || listed.includes(key)) {
+                // A whole value replacing a cut one unmarks its key; an untouched list is left alone.
+                this.truncatedKeys.set(span, keys);
+                span.setAttribute(TRUNCATED_KEY, keys);
+            }
         }
         catch {
             this.instrumentationFailed();

package/dist/environment/types.d.ts

@@ -364,7 +364,11 @@ export interface WorldHandoff {
     baggage: string;
     /** Mirror surfaces of every provider instance the environment version binds. */
     surfaces: WorldSurface[];
-    /** `HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `BAGGAGE`, `TRACEPARENT` and one
+    /** The world's clock at creation (RFC 3339): the date an agent computes its dates from in
+     * place of the wall clock, a trace-built world's recorded start. Also `env.HUE_WORLD_NOW`;
+     * null for a Hue that names neither. */
+    now: string | null;
+    /** `HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `HUE_WORLD_NOW`, `BAGGAGE`, `TRACEPARENT` and one
      * `HUE_SIM_<SURFACE ID>_URL` per surface. */
     env: Record<string, string>;
     /** The `mcpServers` configuration for the MCP surfaces. */
@@ -378,6 +382,9 @@ export interface EnvironmentRun {
     environmentVersionId: string;
     /** Current virtual nanoseconds as a decimal string. */
     clockNs: string;
+    /** The world's clock at creation as an RFC 3339 timestamp (`clockNs` as a date): a
+     * trace-built world's recorded start. Absent from a Hue that predates it. */
+    now?: string;
     /** Digest of current world state. */
     stateDigest: string;
     /** Maximum recorded actions. */

package/dist/environment/world.d.ts

@@ -5,9 +5,22 @@ import type { EnvironmentRun, LegacyMcpCapability, WorldHandoff } from "./types.
  * mirror URLs. The handoff carries the world token; keep it out of logs and checkpoints.
  */
 export declare function worldHandoff(run: EnvironmentRun): WorldHandoff | null;
+/**
+ * The world's clock: what an agent reads for today's date in place of the wall clock, so a
+ * date-relative request (tomorrow, `newer_than:7d`, this month) lands on the dates the world
+ * holds however long after the recording the run starts. From the handoff's `now`, else from
+ * `HUE_WORLD_NOW` in the given environment (this process's by default, where `hue eval
+ * --command` and `agentEnvironment` set it). Null when neither names it.
+ */
+export declare function worldNow(source?: WorldHandoff | Record<string, string | undefined>): Date | null;
 /** Variables that authenticate against Hue's control plane rather than a simulated provider. */
 export declare const HUE_CONTROL_PLANE_VARIABLES: readonly string[];
-/** True for a control-plane variable by name, or for any variable holding a Hue credential. */
+/** Prefixes of the Hue control-plane credentials the server issues: project and setup keys,
+ * attempt grants, the project MCP key, invocation and installation tokens, and OAuth tokens and
+ * secrets. World tokens (`hue_world_`) and MCP capabilities (`hue_sim_`) are what the agent holds. */
+export declare const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES: readonly string[];
+/** True for a control-plane variable by name, or for a value carrying a Hue control-plane
+ * credential anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. */
 export declare function isHueControlPlaneCredential(name: string, value: string | undefined): boolean;
 /** The parent's variables without Hue control-plane credentials; `undefined` values are dropped. */
 export declare function stripHueControlPlaneCredentials(parent: Record<string, string | undefined>): Record<string, string>;

package/dist/environment/world.js

@@ -18,6 +18,7 @@ export function worldHandoff(run) {
         completingUntil: run.completingUntil ?? null,
         traceparent: run.traceparent ?? null,
         baggage: run.baggage ?? `hue-world=${id}`,
+        now: run.now ?? run.env.HUE_WORLD_NOW ?? null,
         surfaces: run.surfaces.map((surface) => ({ ...surface })),
         env: { ...run.env },
         mcpConfig: {
@@ -28,6 +29,22 @@ export function worldHandoff(run) {
         },
     };
 }
+/**
+ * The world's clock: what an agent reads for today's date in place of the wall clock, so a
+ * date-relative request (tomorrow, `newer_than:7d`, this month) lands on the dates the world
+ * holds however long after the recording the run starts. From the handoff's `now`, else from
+ * `HUE_WORLD_NOW` in the given environment (this process's by default, where `hue eval
+ * --command` and `agentEnvironment` set it). Null when neither names it.
+ */
+export function worldNow(source = process.env) {
+    const text = "env" in source && typeof source.env === "object" && source.env !== null
+        ? (source.now ?? source.env.HUE_WORLD_NOW)
+        : source.HUE_WORLD_NOW;
+    if (!text)
+        return null;
+    const date = new Date(text);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
 /** Variables that authenticate against Hue's control plane rather than a simulated provider. */
 export const HUE_CONTROL_PLANE_VARIABLES = [
     "HUE_API_KEY",
@@ -35,13 +52,53 @@ export const HUE_CONTROL_PLANE_VARIABLES = [
     "HUE_PROJECT_KEY",
     "HUE_SERVICE_KEY",
 ];
-/** Hue's own credential shapes: project keys, attempt grants and the project MCP key. */
-const HUE_CREDENTIAL_SHAPE = /^hue_(sk|attempt|mcp)_/;
-/** True for a control-plane variable by name, or for any variable holding a Hue credential. */
+/** Prefixes of the Hue control-plane credentials the server issues: project and setup keys,
+ * attempt grants, the project MCP key, invocation and installation tokens, and OAuth tokens and
+ * secrets. World tokens (`hue_world_`) and MCP capabilities (`hue_sim_`) are what the agent holds. */
+export const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES = [
+    "hue_sk_",
+    "hue_attempt_",
+    "hue_mcp_",
+    "hue_setup_",
+    "hue_inv_",
+    "hue_install_",
+    "hue_at_",
+    "hue_rt_",
+    "hue_oauth_",
+];
+/** A Hue credential anywhere in a value, including JSON Unicode escapes, not inside a longer word. */
+const HUE_CREDENTIAL_SHAPE = new RegExp(`(?:^|[^A-Za-z0-9_])(?:${HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES.join("|")})`);
+const ASCII_PERCENT_ESCAPE = /%[0-7][0-9a-f]/i;
+const ASCII_JSON_UNICODE_ESCAPE = /\\u00([0-7][0-9a-fA-F])/g;
+function decodeAsciiJsonUnicodeEscapes(value) {
+    return value.replace(ASCII_JSON_UNICODE_ESCAPE, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+function hasHueControlPlaneCredential(value) {
+    let candidates = new Set([value]);
+    for (let layer = 0; layer <= 4; layer++) {
+        const jsonDecodedCandidates = new Set();
+        for (const candidate of candidates) {
+            jsonDecodedCandidates.add(candidate);
+            jsonDecodedCandidates.add(decodeAsciiJsonUnicodeEscapes(candidate));
+        }
+        if ([...jsonDecodedCandidates].some((candidate) => HUE_CREDENTIAL_SHAPE.test(candidate)))
+            return true;
+        if (layer === 4)
+            return [...jsonDecodedCandidates].some((candidate) => ASCII_PERCENT_ESCAPE.test(candidate));
+        candidates = new Set([...jsonDecodedCandidates]
+            .filter((candidate) => ASCII_PERCENT_ESCAPE.test(candidate))
+            .map((candidate) => candidate.replace(/%([0-7][0-9a-f])/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))));
+        if (candidates.size === 0)
+            return false;
+    }
+    return false;
+}
+/** True for a control-plane variable by name, or for a value carrying a Hue control-plane
+ * credential anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. */
 export function isHueControlPlaneCredential(name, value) {
     if (HUE_CONTROL_PLANE_VARIABLES.includes(name))
         return true;
-    return typeof value === "string" && HUE_CREDENTIAL_SHAPE.test(value.trim());
+    return typeof value === "string" && hasHueControlPlaneCredential(value);
 }
 /** The parent's variables without Hue control-plane credentials; `undefined` values are dropped. */
 export function stripHueControlPlaneCredentials(parent) {

package/dist/environment.d.ts

@@ -3,5 +3,5 @@ export type { EnvironmentClientOptions } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
 export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./environment/tools.js";
 export type * from "./environment/types.js";
-export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, writeMcpConfig, } from "./environment/world.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";
 export type { AgentEnvironmentOptions, McpConfigFile } from "./environment/world.js";

package/dist/environment.js

@@ -1,3 +1,3 @@
 export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
-export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, writeMcpConfig, } from "./environment/world.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";

package/dist/evals/client.d.ts

@@ -1,6 +1,6 @@
 import type { ProjectConnection } from "../types.js";
 import { type AttemptConnectionBundleV2, type PrepareAttemptRequestV2 } from "./attempt.js";
-import type { ArtifactReservation, ArtifactUpload, CaseConversion, CaseConversionSummary, CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvalSet, EvalSetCase, EvalSetVersion, EvaluationItem, EvaluationRun, EvaluationRunSummary, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Evaluator, EvaluatorVersion, Identity, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Run, RunCase, Scorer, ScorerDefinition, ScorerVersion, Scoring, ScoringResultInput, ScoringResultSummary, ScoringSubject, ScoringSummary, SimulationMcpCapability, StartExecution, Subject, StoredResult, StoredScoringResult } from "./types.js";
+import type { ArtifactReservation, ArtifactUpload, CaseConversion, CaseConversionSummary, CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvalSet, EvalSetCase, EvalSetVersion, EvaluationItem, EvaluationRun, EvaluationRunSummary, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Evaluator, EvaluatorVersion, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Run, RunCase, Scorer, ScorerDefinition, ScorerVersion, Scoring, ScoringResultInput, ScoringResultSummary, ScoringSubject, ScoringSummary, SimulationMcpCapability, StartExecution, Subject, StoredResult, StoredScoringResult, IdentityUpdate, Tag, TaggedIdentity, UpdatedRun } from "./types.js";
 /** Connection options for {@link createEvaluationClient}. */
 export interface EvaluationClientOptions {
     /** Project service key sent as a Bearer token; server side only. */
@@ -79,8 +79,12 @@ export declare class EvaluationClient {
     private registryPage;
     /** Reads the current project to confirm the key and origin. */
     checkConnection(): Promise<ProjectConnection>;
-    /** Creates a dataset with an initial draft version. */
-    createDataset(input: Identity): Promise<Dataset>;
+    /** Creates a dataset with an initial draft version; `tags` names the tags it starts with. */
+    createDataset(input: TaggedIdentity): Promise<Dataset>;
+    /** Renames a dataset or replaces its tags by name; the same values again change nothing. */
+    updateDataset(id: string, input: IdentityUpdate & {
+        slug?: string;
+    }): Promise<Omit<Dataset, "versions">>;
     /** Reads a dataset and its versions. */
     getDataset(id: string): Promise<Dataset>;
     /** Lists datasets without their versions. */
@@ -103,7 +107,14 @@ export declare class EvaluationClient {
     /** Freezes a draft version at the given revision; frozen versions are immutable. */
     freezeDatasetVersion(id: string, expectedRevision: number): Promise<DatasetVersion>;
     /** Creates a scorer identity; publish definitions with {@link publishScorerVersion}. */
-    createScorer(input: Identity): Promise<Scorer>;
+    createScorer(input: TaggedIdentity): Promise<Scorer>;
+    /** Renames a scorer or replaces its tags by name; the same values again change nothing. */
+    updateScorer(id: string, input: IdentityUpdate): Promise<Scorer>;
+    /** Lists the project's tags in the order they were created. */
+    listTags(): Promise<{
+        /** The project's tags. */
+        items: Tag[];
+    }>;
     /** Reads a scorer and its published versions. */
     getScorer(id: string): Promise<Scorer>;
     /** Lists scorers. */
@@ -113,7 +124,11 @@ export declare class EvaluationClient {
     /** Reads a published scorer version. */
     getScorerVersion(id: string): Promise<ScorerVersion>;
     /** Creates an eval set using the existing v1 registry path. */
-    createEvalSet(input: Identity): Promise<EvalSet>;
+    createEvalSet(input: TaggedIdentity): Promise<EvalSet>;
+    /** Renames an eval set or replaces its tags by name. */
+    updateEvalSet(id: string, input: IdentityUpdate & {
+        slug?: string;
+    }): Promise<Omit<EvalSet, "versions">>;
     /** Reads an eval set and its versions. */
     getEvalSet(id: string): Promise<EvalSet>;
     /** Lists eval sets. */
@@ -136,7 +151,9 @@ export declare class EvaluationClient {
     /** Freezes a draft eval set version at its expected revision. */
     freezeEvalSetVersion(id: string, expectedRevision: number): Promise<EvalSetVersion>;
     /** Creates an evaluator identity. */
-    createEvaluator(input: Identity): Promise<Evaluator>;
+    createEvaluator(input: TaggedIdentity): Promise<Evaluator>;
+    /** Renames an evaluator or replaces its tags by name. */
+    updateEvaluator(id: string, input: IdentityUpdate): Promise<Evaluator>;
     /** Reads an evaluator and its published versions. */
     getEvaluator(id: string): Promise<Evaluator>;
     /** Lists evaluators. */
@@ -152,6 +169,8 @@ export declare class EvaluationClient {
         datasetVersionId: string;
         scorerVersionIds: string[];
         config: JsonValue;
+        /** The experiment's own tag names; it also shows its dataset's tags. */
+        tags?: string[];
     }): Promise<{
         /** Experiment ID. */
         id: string;
@@ -160,6 +179,11 @@ export declare class EvaluationClient {
     }>;
     /** Reads an experiment with its evaluation run and execution counts. */
     getExperiment(id: string): Promise<Experiment>;
+    /** Renames an experiment or replaces its own tags by name. */
+    updateExperiment(id: string, input: {
+        name?: string;
+        tags?: string[];
+    }): Promise<UpdatedRun>;
     /** Lists an experiment's cases with their latest executions. */
     listExperimentItems(id: string, page?: PageOptions): Promise<Page<ExperimentItem>>;
     /** Reads one frozen case of an experiment. */
@@ -261,6 +285,8 @@ export declare class EvaluationClient {
         evalSetVersionId: string;
         evaluatorVersionIds: string[];
         config: JsonValue;
+        /** The run's own tag names; it also shows its eval set's tags. */
+        tags?: string[];
     }): Promise<{
         /** Run ID. */
         id: string;
@@ -271,6 +297,11 @@ export declare class EvaluationClient {
     }>;
     /** Reads a run with its scoring progress. */
     getRun(id: string): Promise<Run>;
+    /** Renames a run or replaces its own tags by name; its eval set's tags are not its own. */
+    updateRun(id: string, input: {
+        name?: string;
+        tags?: string[];
+    }): Promise<UpdatedRun>;
     /** Lists a run's cases with their latest executions. */
     listRunItems(id: string, page?: PageOptions): Promise<Page<ExperimentItem>>;
     /** Reads one frozen case of a run. */