@hue-run/sdk 0.12.0 → 0.13.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.12.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.13.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.
 
@@ -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.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.0.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.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -576,7 +576,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: read
+today's date from it, never from the wall clock), 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
@@ -618,6 +620,11 @@ for example, needs a reviewed `attemptBaselineV2` (see
 registers none, so put `"attemptBaselineV2"` in the run's configuration JSON when you launch the
 run from Hue.
 
+`--trace-not-accepted pending` completes a case whose telemetry Hue did not accept in time in its
+true state with the trace still to arrive, carrying the count of spans the case ended; Hue scores
+the sealed world at once and attaches the trace once its export is complete. The default,
+`fail_case`, completes such a case as failed with its evidence omitted.
+
 A Scenario or eval set whose dataset version is not saved cannot back an experiment: the command
 exits 1 and asks for **Save eval-set version** in Hue or `--save-version`, which freezes that
 version at its current revision. Connection settings are `HUE_API_KEY` and `HUE_BASE_URL`
@@ -663,9 +670,9 @@ an interrupted run without invoking the agent again; a different selection is re
 unfinished one is resumed or its directory is removed.
 
 Exit codes: `0` every case passed the evaluators that apply to it (advisory ones never count),
-`1` a case failed, errored (including one no pinned evaluator applies to or decides), was skipped
-or Hue's checks were
-still pending at `--wait`, `2` usage or configuration error (including a missing key), `130`
+`1` a case failed, errored (including one no pinned evaluator applies to or decides), was skipped,
+was inconclusive (a required judge could not run or answer; the table says `INCONCLUSIVE` and the
+summary counts it apart from skipped cases) or Hue's checks were still pending at `--wait`, `2` usage or configuration error (including a missing key), `130`
 interrupted. On Node.js 22, load TypeScript adapters with `NODE_OPTIONS=--experimental-strip-types`;
 non-erasable syntax (enums, parameter properties, namespaces) needs a loader such as `--import tsx`
 on any Node.js version.

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 {

package/EVALUATIONS.md

@@ -116,7 +116,7 @@ Both choices are required and independent:
 
 Frozen dataset inputs/references already exist on Hue. Their presence is independent of these switches. No output is inferred from telemetry. JavaScript `undefined` means unavailable output; JSON `null`, false, zero and empty string remain present values. Historical subjects with unavailable output produce skipped results without executing a scorer callback. A failed quality metric remains `state:"scored"` with `passed:false`. Target errors and scorer errors remain separate. Target error types are generalized to `TargetError`; when content is enabled, bounded messages may be stored. Never put credentials in error messages, output, custom metric values, names or metadata.
 
-`traceEvidence:{mode:"required"}` waits for trace and log export acknowledgement after the root span ends. The transport is shared by every case in flight, so each export issue names the traces of the records it concerned (`ExportIssue.traceIds`): a refused or rejected batch, a dropped record, a capture failure inside a case. A failure that names the case's trace is that case's own and final (its checkpoint reads `failed`, and resume refuses it); one that names only other traces leaves the case accepted; one that names no trace (a processor flush that failed) or a rejection in a batch of several traces is decided by the case's trace receipt, at once or on resume for a checkpoint still `pending`: the receipt must hold the case's root span and at least as many spans as the case ended (the checkpoint records the count at the flush; without it the receipt does not accept). The explicit alternative `{mode:"omit",reason:"..."}` stores the omission reason and declared trace ID without a fake snapshot. It can complete despite an export failure; export diagnostics remain available on the Hue client. There is no automatic fallback to omission. When required telemetry is not accepted, the runner by default keeps the saved outcome, leaves the execution started and rejects (`traceNotAccepted: "stop"`). With `traceNotAccepted: "fail_case"` it instead completes that case as failed (a `TelemetryNotAccepted` error, the evidence omitted with a reason starting `telemetry_not_accepted`, and no output or generated files attached, so no scorer can pass it), calls `onTelemetryNotAccepted(entry)` once, as soon as it completes the case (a resumed call only lists it), lists it in `report.telemetryNotAccepted` with sanitized issue counts, and goes on; `hue eval` uses this. A scorer that grades only the world can still score such a case, so treat a listed case as failed whatever its results say, as `hue eval` does.
+`traceEvidence:{mode:"required"}` waits for trace and log export acknowledgement after the root span ends. The transport is shared by every case in flight, so each export issue names the traces of the records it concerned (`ExportIssue.traceIds`): a refused or rejected batch, a dropped record, a capture failure inside a case. A failure that names the case's trace is that case's own and final (its checkpoint reads `failed`, and resume refuses it); one that names only other traces leaves the case accepted; one that names no trace (a processor flush that failed) or a rejection in a batch of several traces is decided by the case's trace receipt, at once or on resume for a checkpoint still `pending`: the receipt must hold the case's root span and at least as many spans as the case ended (the checkpoint records the count at the flush; without it the receipt does not accept). The explicit alternative `{mode:"omit",reason:"..."}` stores the omission reason and declared trace ID without a fake snapshot. It can complete despite an export failure; export diagnostics remain available on the Hue client. There is no automatic fallback to omission. When required telemetry is not accepted, the runner by default keeps the saved outcome, leaves the execution started and rejects (`traceNotAccepted: "stop"`). With `traceNotAccepted: "fail_case"` it instead completes that case as failed (a `TelemetryNotAccepted` error, the evidence omitted with a reason starting `telemetry_not_accepted`, and no output or generated files attached, so no scorer can pass it), calls `onTelemetryNotAccepted(entry)` once, as soon as it completes the case (a resumed call only lists it), lists it in `report.telemetryNotAccepted` with sanitized issue counts, and goes on; `hue eval` uses this. A scorer that grades only the world can still score such a case, so treat a listed case as failed whatever its results say, as `hue eval` does. `traceNotAccepted:"pending"` completes a case whose telemetry Hue did not accept in time in its true state with `traceEvidence:"pending"` and the count of spans the case ended (`traceSpanCount`): Hue scores the sealed world at once, attaches the trace once it holds every span (a root span alone is not the trace), or records the evidence omitted a day later; such cases are listed in `RunnerReport.tracePending`. A saved outcome whose export the receipt does not accept on resume completes the same way. `hue eval --trace-not-accepted pending` chooses it for the CLI.
 
 ## Local scorers
 
@@ -371,6 +371,8 @@ files directory must be owned by the current user and closed to everyone else (m
 target again; if result content is not persisted, the JSON output cannot be reconstructed and the
 case is reported as uncertain.
 
+A target that throws completes its execution as `error` with a type that says what stopped the case. `TargetError` is the agent's own failure. A service the agent called that refused with a retryable status (408, 429 or 5xx, such as a model provider's rate limit or outage, when the error carries the exchange: headers, a response or a URL) is `ServiceRefused`; a connection that failed (`ECONNRESET`, `ECONNREFUSED`, `fetch failed`, an `APIConnectionError`) is `ConnectionFailed`; a call that timed out (`TimeoutError`, `APITimeoutError`) is `TimedOut`. The runner reads the error's `cause`, `lastError` and `errors` chains for these signals. Hue counts the three as infrastructure and leaves them out of the agent's pass rate; a refusal the agent caused (a 400 from a model provider or another service) stays `TargetError`. Any other status Hue's own clients answered with (a 4xx: a key, a project, an environment version or a world Hue refused) is `ConfigurationRejected`, which Hue counts as configuration and also leaves out of the agent's pass rate: an error from Hue's own clients is never the agent's. The clients fetch with `redirect: "error"`, so a redirect from the configured endpoint surfaces without a status, as `ConnectionFailed`. A runner of your own that completes an execution with a `type` of its own can say which class Hue files it under with the error's `class`.
+
 `rescore` downloads a subject's frozen `files` — the pinned inputs and the generated outputs, with
 `role: "output"` for the documents a run produced — so a code evaluator can grade saved documents
 without invoking an agent. Local scorers receive them as `context.files` exactly as they do during

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/cli/eval.js

@@ -83,16 +83,28 @@ Output and limits:
   --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-64 (default: 1)
+  --trace-not-accepted <policy>   A case whose telemetry Hue did not accept in time: fail_case
+                                  (default) completes it as failed with the evidence omitted;
+                                  pending completes it in its true state with the trace still to
+                                  arrive, which Hue attaches once its export is complete
   --timeout <seconds>             Per-case --command timeout (default: 600)
   --wait <seconds>                Verdict wait after the run finishes (default: 300)
   -h, --help                      Show this help
 
 HUE_API_KEY must be a "Read and write" project key; it is never printed.
 Code evaluators pinned to a direct run are graded by Hue's executor after the upload; the wait
-covers them. Exit codes: 0 every case passed, 1 a case failed, errored or is incomplete,
-2 usage error, 130 interrupted.
+covers them. Exit codes: 0 every case passed, 1 a case failed, errored, is inconclusive or is
+incomplete, 2 usage error, 130 interrupted.
 `;
 /** Thrown for invalid arguments or configuration; exits with status 2. */
+/** The `--trace-not-accepted` policy: the failed-case default, or pending evidence. */
+function traceNotAcceptedPolicy(value) {
+    if (value === undefined || value === "fail_case")
+        return "fail_case";
+    if (value === "pending")
+        return "pending";
+    throw new UsageError("--trace-not-accepted must be fail_case or pending");
+}
 class UsageError extends Error {
     constructor(message) {
         super(message);
@@ -129,6 +141,7 @@ function parse(argv) {
                 json: { type: "boolean", default: false },
                 content: { type: "boolean", default: false },
                 "no-output": { type: "boolean", default: false },
+                "trace-not-accepted": { type: "string" },
                 "save-version": { type: "boolean", default: false },
                 "checkpoint-dir": { type: "string" },
                 concurrency: { type: "string" },
@@ -702,6 +715,11 @@ const STATE_LABEL = {
     skipped: "SKIPPED",
     pending: "PENDING",
 };
+/** A skipped case whose deciding evaluator could not decide it, as an answer-graded case whose
+ * required judge could not run or answer: Hue's explanation begins "Inconclusive:". It is named
+ * apart from a case its evaluators did not grade, since it needs a judge, not another pin. */
+const inconclusive = (item) => item.state === "skipped" && item.explanations.some((text) => /^inconclusive:/i.test(text));
+const stateLabel = (item) => inconclusive(item) ? "INCONCLUSIVE" : STATE_LABEL[item.state];
 export function renderTable(verdicts, output) {
     const cases = verdicts.summary.cases;
     // A column per metric name; a name several evaluators report, such as two judges' `verdict`,
@@ -736,7 +754,7 @@ export function renderTable(verdicts, output) {
             // reporting the metric shows "-".
             return item.notApplicable?.includes(column.version) ? "n/a" : "-";
         }),
-        STATE_LABEL[item.state],
+        stateLabel(item),
     ]);
     const widths = header.map((cell, index) => Math.max(cell.length, ...rows.map((row) => row[index].length)));
     const line = (cells) => cells
@@ -751,15 +769,18 @@ export function renderTable(verdicts, output) {
         if (item.state === "passed")
             continue;
         const details = [...item.errors.map((type) => `scorer error ${type}`), ...item.explanations];
-        for (const detail of details.length ? details : [STATE_LABEL[item.state].toLowerCase()])
+        for (const detail of details.length ? details : [stateLabel(item).toLowerCase()])
             output.log(`  ${item.externalKey}: ${detail}`);
     }
     const totals = verdicts.summary.totals;
+    const inconclusiveCount = cases.filter(inconclusive).length;
+    const skipped = totals.skipped - inconclusiveCount;
     const advisoryFailures = cases.reduce((count, item) => count +
         item.metrics.filter((metric) => item.advisory?.includes(metric.scorerVersionId) && !metricPassed(metric)).length, 0);
     const extra = [
         totals.error ? `${totals.error} error` : "",
-        totals.skipped ? `${totals.skipped} skipped` : "",
+        inconclusiveCount ? `${inconclusiveCount} inconclusive` : "",
+        skipped > 0 ? `${skipped} skipped` : "",
         totals.pending ? `${totals.pending} pending` : "",
         totals.notApplicable
             ? `${totals.notApplicable} evaluator result${totals.notApplicable === 1 ? "" : "s"} not applicable`
@@ -1116,7 +1137,7 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
         persistResultContent: !values["no-output"],
         traceEvidence: { mode: "required" },
         // A case whose telemetry Hue did not accept fails instead of staying started.
-        traceNotAccepted: "fail_case",
+        traceNotAccepted: traceNotAcceptedPolicy(values["trace-not-accepted"]),
         onTelemetryNotAccepted: telemetry.report,
         concurrency,
         agentRevision: agent.revision,
@@ -1221,7 +1242,7 @@ async function runDirect(run, connection) {
             // only the telemetry.
             persistResultContent: !values["no-output"],
             traceEvidence: { mode: "required" },
-            traceNotAccepted: "fail_case",
+            traceNotAccepted: traceNotAcceptedPolicy(values["trace-not-accepted"]),
             onTelemetryNotAccepted: telemetry.report,
             concurrency: run.concurrency,
             scorers: [],
@@ -1297,7 +1318,7 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
         },
         scorers: [],
         concurrency,
-        traceNotAccepted: "fail_case",
+        traceNotAccepted: traceNotAcceptedPolicy(values["trace-not-accepted"]),
         onTelemetryNotAccepted: telemetry.report,
         deprecationWarnings: false,
         signal,
@@ -1402,6 +1423,8 @@ export async function runEvalCommand(argv) {
     let json = false;
     try {
         const { values, positionals } = parse(argv);
+        // A usage error before anything is prepared or created: no run is left to recover from it.
+        traceNotAcceptedPolicy(values["trace-not-accepted"]);
         json = values.json;
         const output = {
             log: (line) => (json ? process.stderr : process.stdout).write(`${line}\n`),

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,6 +5,14 @@ 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. */

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",

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_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_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";

package/dist/evals/failure.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a target's throw shows about a service the agent called, when a service rather than the
+ * agent's own code stopped it: `ServiceRefused` for a retryable HTTP status (408, 429 or 5xx) a
+ * model provider, Hue or another service answered with, such as a rate limit or an outage;
+ * `ConnectionFailed` for a connection that failed; `TimedOut` for a call that timed out; and
+ * `ConfigurationRejected` for any other status Hue's own clients answered with (a 4xx: a key, a
+ * project, an environment version or a world Hue refused), which is the caller's configuration;
+ * the clients fetch with `redirect: "error"`, so a redirect surfaces without a status, as a
+ * failed connection.
+ * The runner records the type on the execution in place of `TargetError`; Hue classes the first
+ * three as infrastructure and the last as configuration, so an error from Hue's own clients is
+ * never filed as the agent's. Anything else is the agent's own error.
+ *
+ * A simulated world the agent reaches through its own client (an MCP client, a REST client, a
+ * fetch) answers Hue's gateway refusals with a status and a diagnostic: `503
+ * authorization_unavailable` when Hue could not authorize the world token because its database
+ * could not answer, `503 gateway_failure` when the gateway failed. The MCP SDK's transport throws
+ * these as `StreamableHTTPError` or `SseError` with the status as `code` and no response, so the
+ * status is read from there too; the diagnostic is the error's cause (`serviceFailureCause`),
+ * recorded beside the type so a run's reader sees what refused it.
+ */
+export type ServiceFailureType = "ServiceRefused" | "ConnectionFailed" | "TimedOut" | "ConfigurationRejected";
+/** The service failure a target's throw shows, by the errors linked from it, in precedence
+ * order: a timeout, a failed connection, a retryable refusal, a status Hue's own client was
+ * refused with; null for the agent's own error. */
+export declare function serviceFailureType(error: unknown): ServiceFailureType | null;
+/**
+ * The service's own word for what failed, when the answer a target's throw carries names one:
+ * Hue's gateway diagnostic (`authorization_unavailable`, `gateway_failure`), read from the
+ * `x-hue-diagnostic` header or the JSON body's `diagnostic` of any error linked from the throw,
+ * nearest first. Undefined when no answer names one, or the name is not a diagnostic's token.
+ * Read for a service failure (`serviceFailureType`), where the runner records it as the error's
+ * `cause`.
+ */
+export declare function serviceFailureCause(error: unknown): string | undefined;