@hue-run/sdk 0.13.0 → 0.13.2

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.13.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.13.2`, `@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.13.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.2.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.13.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.13.2.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.2 --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.2 --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.2 --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.2 --package "zod@^4.6.5" hue eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision> --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.2 --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.
@@ -558,9 +581,11 @@ Failing cases print the scorer explanation. An evaluator Hue records as not appl
 that case's columns and neither passes nor fails it, so in a mixed eval set a case is decided by
 the evaluators that apply to it; the pass line counts the not-applicable results. A case that no
 pinned evaluator applies to is an error that names what they need. A result of a pinned Hue judge
-(an evaluator of kind `world_judge`) that Hue marks advisory, as it does every judge's today, is
+(an evaluator of kind `world_judge`) that Hue marks advisory is
 shown in its column, marked `(advisory)`, but never decides a case or the exit code; the pass line
-counts advisory failures as not counted, and a case only advisory results ran for is an error. Any
+counts advisory failures as not counted, and a case only advisory results ran for is an error.
+The Answer outcome evaluator uses its required judge to decide answer-only cases; if that judge
+cannot run, the case is inconclusive. Any
 other evaluator's result, an error, or a metric that carries `passed` is never advisory, whatever
 its evidence says. A metric name that
 several evaluators report, such as two judges' `verdict`, gets a column per evaluator, labelled
@@ -576,8 +601,8 @@ 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`, `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
+(`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
@@ -606,8 +631,21 @@ 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:
-`AGENT_REVISION`, then the Git `HEAD` short hash, then `dev`) and capability `environment:v1`
-plus any repeated `--capability <value>`, prints the registration and each claimed run with its
+`AGENT_REVISION`, then the Git `HEAD` short hash, then `dev`). Command workers register both
+`environment:v1` and `direct:v1`, plus any repeated `--capability <value>`: the same worker runs
+world cases, answer-only cases and mixed eval sets launched from Hue. Commands keep the launch
+directory for both case kinds, so relative application entry points and configuration work.
+Direct cases receive the task/config on stdin and private files/output through `HUE_CASE_*`,
+without a world token, MCP connection or `HUE_ENVIRONMENT_RUN_ID`. App calls that require a world
+must stay disabled for this handoff; never fall back to live app credentials.
+
+Adapter-file workers register `environment:v1` by default. Add `--capability direct:v1` only when
+the adapter also handles `context.mode === "direct"`; its direct context carries `config`, case
+identity, `executionId`, `files`, `outputDirectory` and `signal`, with no world or tools. These
+worker behaviors are added in TypeScript 0.13.2. Upgrading an existing command worker requires a
+new `--revision`, because adding a capability to a previously registered revision is refused.
+
+The worker prints the registration and each claimed run with its
 URL, executes runs launched from Hue until Ctrl+C or `--max-runs <n>`, and prints the verdict table
 after each run. Selection flags do not apply; Hue chooses the pinned experiment. The worker exits 0
 when it stops normally. Hue offers a case whose world comes with agent-visible files only to a

package/ENVIRONMENTS.md

@@ -328,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
@@ -279,12 +297,19 @@ acceptance remains a post-publication Fern gate.
 
 ## Direct cases and files
 
-Cases without a simulated world — document workflows whose inputs are a task plus pinned files —
+Cases without a simulated world — answer-only tasks, or document workflows with pinned files —
 run on the same runner under the same checkpoint rules. They shipped in `@hue-run/sdk` `0.5.0`
 and require a Hue deployment that serves case `inputFiles` on experiment
 items, subject `files`, and the artifact reservation, upload, completion and download APIs. The
 Python SDK has no equivalent.
 
+The TypeScript 0.13.2 `hue eval --worker --command "…"` wrapper supplies both callbacks, so one
+command worker accepts direct and world cases, including mixed eval sets. It keeps the launch
+directory for relative application entry points; private case inputs/output still use
+`HUE_CASE_*`. An adapter-file worker opts into the direct callback with `--capability direct:v1`
+and must handle `context.mode === "direct"`. Restart an existing environment-only command
+registration with a new `--revision` when upgrading.
+
 On the outbound worker, supply `directTarget` beside or instead of `target`. Supplying
 `directTarget` registers the `direct:v1` capability and supplying `target` registers
 `environment:v1` (both strings are exported as `localAgentCapabilities`). Declare the file

package/README.md

@@ -647,10 +647,12 @@ their agents with `runLocalAgent()`; setup does not register workers or launch s
 The `hue eval` command, shipped in TypeScript `0.5.0` (`--case` since `0.6.0`, `--scenario`
 before), wraps `runSimulation()` and `runLocalAgent()` for an adapter file or a shell command:
 `hue eval --case "<name>" ./hue-agent.ts --content` creates a fresh run from a published case's
-immutable pins, runs the agent in one isolated world per case, waits
+immutable pins, runs the agent with an isolated world when the case pins one, waits
 for Hue's outcome checks and prints the run URL and per-case PASS/FAIL verdicts with an exit code;
-`--worker` registers the same adapter for runs launched from Hue. It needs a Read and
-write key in `HUE_API_KEY` (never printed). Content capture stays off unless `--content` is
+`--worker` registers the same adapter for runs launched from Hue. In TypeScript 0.13.2, a
+command worker handles both world and answer-only cases; adapter workers opt into direct cases
+with `--capability direct:v1`. Upgrade an existing command registration under a new `--revision`.
+It needs a Read and write key in `HUE_API_KEY` (never printed). Content capture stays off unless `--content` is
 passed; the example passes it so case spans carry content. Case outputs, error messages and
 explanations are stored in Hue either way (`--no-output` keeps them out of a one-shot run's
 results); a command's stdout is its stored answer, with the credentials `hue eval` handed the case

package/dist/cli/eval.js

@@ -60,6 +60,8 @@ Agent (exactly one):
 
 Modes:
   --worker                        Register the agent and poll for runs launched from Hue
+                                  Commands support cases with or without a world; adapter files
+                                  opt into direct cases with --capability direct:v1
   --max-runs <n>                  Stop the worker after n completed runs
   --agent-key <key>               Agent key (default: slug of the adapter filename)
   --agent-name <name>             Agent display name (default: the key)
@@ -600,9 +602,11 @@ function redacting(adapter) {
 function parentEnvironment(allowHueCredentials) {
     // A world variable left in this process's environment belongs to another world: only the
     // current case's world sets them, whether or not the case has one.
-    return withoutWorldVariables(allowHueCredentials
+    const parent = withoutWorldVariables(allowHueCredentials
         ? Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined))
         : stripHueControlPlaneCredentials(process.env));
+    delete parent.HUE_ENVIRONMENT_RUN_ID;
+    return parent;
 }
 function commandAdapter(command, timeoutSeconds, options) {
     return async (inputs, context) => {
@@ -683,7 +687,7 @@ function directCommandAdapter(command, timeoutSeconds, options) {
             files: context.files,
         });
         const stdout = await spawnAgentCommand(command, {
-            cwd: layout.caseDirectory,
+            cwd: options.workingDirectory ?? layout.caseDirectory,
             env: {
                 ...parentEnvironment(options.allowHueCredentials),
                 HUE_CASE_DIR: layout.caseDirectory,
@@ -1286,7 +1290,7 @@ async function runDirect(run, connection) {
         telemetryNotAccepted: report.telemetryNotAccepted,
     }, run.baselineId, output, signal);
 }
-async function runWorker(values, connection, adapter, agent, hue, output, signal) {
+async function runWorker(values, connection, agents, agent, hue, output, signal) {
     const client = new ObservedClient(connection);
     const environmentClient = createEnvironmentClient(connection);
     const wait = integer("wait", values.wait, 300, 0, 86_400);
@@ -1305,6 +1309,9 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
         output.log(`Claimed run ${claim.runId}: ${new URL(`/experiments/${claim.experimentId}`, connection.baseUrl).toString()}`);
     };
     const telemetry = telemetryReporter(output);
+    // A command can use the same stdin contract for both case kinds. Existing adapter files
+    // may require a world, so their direct context remains an explicit capability opt-in.
+    const direct = values.command !== undefined || values.capability?.includes("direct:v1");
     await runLocalAgent({
         client,
         environmentClient,
@@ -1339,7 +1346,7 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
         },
         target(inputs, tools, context) {
             output.log(`[${context.item.externalKey}] agent started`);
-            return adapter(inputs, {
+            return agents.simulation(inputs, {
                 config: context.config,
                 item: context.item,
                 executionId: context.executionId,
@@ -1355,6 +1362,22 @@ async function runWorker(values, connection, adapter, agent, hue, output, signal
                 signal: context.signal ?? signal,
             });
         },
+        ...(direct
+            ? {
+                directTarget(inputs, context) {
+                    output.log(`[${context.item.externalKey}] agent started`);
+                    return agents.direct(inputs, {
+                        mode: "direct",
+                        config: context.config,
+                        item: context.item,
+                        executionId: context.executionId,
+                        files: context.files,
+                        outputDirectory: context.outputDirectory,
+                        signal: context.signal ?? signal,
+                    });
+                },
+            }
+            : {}),
         async onCompleted(report) {
             output.log(`Run ${report.runId} completed: ${report.subjectIds.length} case${report.subjectIds.length === 1 ? "" : "s"}`);
             telemetry.rest(report.telemetryNotAccepted);
@@ -1490,6 +1513,9 @@ export async function runEvalCommand(argv) {
             direct: redacting(loaded ??
                 directCommandAdapter(values.command, timeout, {
                     allowHueCredentials: values["allow-hue-credentials"],
+                    // A worker's single command must resolve relative entry points the same way for
+                    // direct and world cases. One-shot direct runs keep their private-directory cwd.
+                    ...(values.worker ? { workingDirectory: process.cwd() } : {}),
                 })),
         };
         hue = createHue({
@@ -1500,7 +1526,7 @@ export async function runEvalCommand(argv) {
             timeoutMillis: CASE_TRACE_EXPORT_MILLIS,
         });
         return values.worker
-            ? await runWorker(values, connection, agents.simulation, agent, hue, output, controller.signal)
+            ? await runWorker(values, connection, agents, agent, hue, output, controller.signal)
             : await runOnce(values, connection, agents, agent, hue, output, controller.signal);
     }
     catch (error) {

package/dist/environment/world.d.ts

@@ -15,7 +15,12 @@ export declare function worldHandoff(run: EnvironmentRun): WorldHandoff | null;
 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

@@ -52,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, worldNow, 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, worldNow, 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 its order: as people arranged them in Hue, then newer tags. */
+    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. */

package/dist/evals/client.js

@@ -89,6 +89,15 @@ function productRegistryFields(value) {
     }
     return result;
 }
+/** Tag names travel as given; anything but a list of strings is a caller error. */
+function tagNames(tags) {
+    if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === "string"))
+        throw new TypeError("tags must be a list of tag names");
+    return tags;
+}
+function withTagNames(input) {
+    return input.tags === undefined ? input : { ...input, tags: tagNames(input.tags) };
+}
 const runResponseAliases = [
     ["datasetId", "evalSetId"],
     ["datasetName", "evalSetName"],
@@ -388,15 +397,21 @@ export class EvaluationClient {
         const query = new URLSearchParams(this.page(options).slice(1));
         if (options.includeArchived !== undefined)
             query.set("includeArchived", String(options.includeArchived));
+        for (const tag of tagNames(options.tags ?? []))
+            query.append("tag", tag);
         return query.size ? `?${query}` : "";
     }
     /** Reads the current project to confirm the key and origin. */
     checkConnection() {
         return this.request("GET", "/projects/current");
     }
-    /** Creates a dataset with an initial draft version. */
+    /** Creates a dataset with an initial draft version; `tags` names the tags it starts with. */
     createDataset(input) {
-        return this.request("POST", "/datasets", input);
+        return this.request("POST", "/datasets", withTagNames(input));
+    }
+    /** Renames a dataset or replaces its tags by name; the same values again change nothing. */
+    updateDataset(id, input) {
+        return this.request("PATCH", `/datasets/${uuid(id)}`, withTagNames(input), undefined, undefined, true);
     }
     /** Reads a dataset and its versions. */
     getDataset(id) {
@@ -430,7 +445,15 @@ export class EvaluationClient {
     }
     /** Creates a scorer identity; publish definitions with {@link publishScorerVersion}. */
     createScorer(input) {
-        return this.request("POST", "/scorers", input);
+        return this.request("POST", "/scorers", withTagNames(input));
+    }
+    /** Renames a scorer or replaces its tags by name; the same values again change nothing. */
+    updateScorer(id, input) {
+        return this.request("PATCH", `/scorers/${uuid(id)}`, withTagNames(input), undefined, undefined, true);
+    }
+    /** Lists the project's tags in its order: as people arranged them in Hue, then newer tags. */
+    listTags() {
+        return this.request("GET", "/tags");
     }
     /** Reads a scorer and its published versions. */
     getScorer(id) {
@@ -452,6 +475,10 @@ export class EvaluationClient {
     async createEvalSet(input) {
         return productRegistryFields(await this.createDataset(input));
     }
+    /** Renames an eval set or replaces its tags by name. */
+    async updateEvalSet(id, input) {
+        return productRegistryFields(await this.updateDataset(id, input));
+    }
     /** Reads an eval set and its versions. */
     async getEvalSet(id) {
         return productRegistryFields(await this.getDataset(id));
@@ -484,6 +511,10 @@ export class EvaluationClient {
     async createEvaluator(input) {
         return productRegistryFields(await this.createScorer(input));
     }
+    /** Renames an evaluator or replaces its tags by name. */
+    async updateEvaluator(id, input) {
+        return productRegistryFields(await this.updateScorer(id, input));
+    }
     /** Reads an evaluator and its published versions. */
     async getEvaluator(id) {
         return productRegistryFields(await this.getScorer(id));
@@ -502,12 +533,16 @@ export class EvaluationClient {
     }
     /** Creates an experiment over a frozen dataset version with pinned scorer versions and a configuration. */
     createExperiment(input) {
-        return this.request("POST", "/experiments", input);
+        return this.request("POST", "/experiments", withTagNames(input));
     }
     /** Reads an experiment with its evaluation run and execution counts. */
     getExperiment(id) {
         return this.request("GET", `/experiments/${uuid(id)}`);
     }
+    /** Renames an experiment or replaces its own tags by name. */
+    updateExperiment(id, input) {
+        return this.request("PATCH", `/experiments/${uuid(id)}`, withTagNames(input), undefined, undefined, true);
+    }
     /** Lists an experiment's cases with their latest executions. */
     listExperimentItems(id, page) {
         return this.request("GET", `/experiments/${uuid(id)}/items${this.page(page)}`);
@@ -656,12 +691,16 @@ export class EvaluationClient {
     }
     /** Creates a run using product request fields on the existing v1 path. */
     async createRun(input) {
-        return productRunFields(await this.request("POST", "/experiments", input), "run");
+        return productRunFields(await this.request("POST", "/experiments", withTagNames(input)), "run");
     }
     /** Reads a run with its scoring progress. */
     async getRun(id) {
         return productRunFields(await this.getExperiment(id), "run");
     }
+    /** Renames a run or replaces its own tags by name; its eval set's tags are not its own. */
+    async updateRun(id, input) {
+        return this.updateExperiment(id, input);
+    }
     /** Lists a run's cases with their latest executions. */
     async listRunItems(id, page) {
         return productRunFields(await this.listExperimentItems(id, page), "run");

package/dist/evals/scorer-publication.js

@@ -5,18 +5,25 @@ const metricName = z
     .min(1)
     .max(64)
     .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/);
+const metricDescription = z.string().trim().min(1).max(500).optional();
 const metric = z.discriminatedUnion("type", [
-    z.strictObject({ name: metricName, type: z.literal("boolean") }),
-    z.strictObject({ name: metricName, type: z.literal("text") }),
+    z.strictObject({
+        name: metricName,
+        type: z.literal("boolean"),
+        description: metricDescription,
+    }),
+    z.strictObject({ name: metricName, type: z.literal("text"), description: metricDescription }),
     z.strictObject({
         name: metricName,
         type: z.literal("number"),
+        description: metricDescription,
         min: z.number().finite().optional(),
         max: z.number().finite().optional(),
     }),
     z.strictObject({
         name: metricName,
         type: z.literal("category"),
+        description: metricDescription,
         categories: z.array(z.string()).min(1),
     }),
 ]);
@@ -135,12 +142,17 @@ const sdkScorerPublication = z.union([
     }),
     z.strictObject({
         kind: z.literal("world_outcome"),
-        entry: z.literal("hue.outcome_assertions.v2"),
+        entry: z.enum([
+            "hue.outcome_assertions.v2",
+            "hue.outcome_assertions.v4",
+            "hue.outcome_assertions.v5",
+            "hue.outcome_assertions.v6",
+        ]),
         metrics: fixedMetrics(outcomeAssertionMetrics),
     }),
     z.strictObject({
         kind: z.literal("world_outcome"),
-        entry: z.literal("hue.outcome_assertions.v3"),
+        entry: z.enum(["hue.outcome_assertions.v3", "hue.answer_outcome.v1", "hue.answer_outcome.v2"]),
         metrics: fixedMetrics(outcomeAssertionV3Metrics),
         config: z.strictObject({ judge: outcomeJudgeConfig }),
     }),

package/dist/evals/scorers.js

@@ -32,7 +32,9 @@ export function defineLocalScorer(options) {
             language: "typescript",
             entrypoint: options.entrypoint,
             sourceDigest: sourceDigest(options.source),
-            metrics: options.metrics,
+            metrics: options.metrics.map((metric) => metric.description === undefined
+                ? metric
+                : { ...metric, description: metric.description.trim() }),
         },
         score: options.score,
     };

package/dist/evals/types.d.ts

@@ -19,6 +19,8 @@ export interface PageOptions {
 export interface RegistryPageOptions extends PageOptions {
     /** Include archived identities so callers can diagnose slug conflicts explicitly. */
     includeArchived?: boolean;
+    /** Only identities carrying any of these tag names, matched without case. */
+    tags?: string[];
 }
 /** Human-readable identity of a dataset or scorer. */
 export interface Identity {
@@ -29,12 +31,50 @@ export interface Identity {
     /** Optional description. */
     description?: string;
 }
+/** A dataset or scorer to create, with the names of the tags it starts with. */
+export interface TaggedIdentity extends Identity {
+    /** Tag names; a name the project has no tag for creates one. */
+    tags?: string[];
+}
+/** Identity fields and tags to change on a dataset or scorer; omitted fields stay. */
+export interface IdentityUpdate {
+    /** New display name. */
+    name?: string;
+    /** New description. */
+    description?: string;
+    /** Every tag name the item should carry; replaces its tags. */
+    tags?: string[];
+}
+/** An experiment's (run's) name and tags after an update. */
+export interface UpdatedRun {
+    /** Experiment (run) ID. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** The experiment's own tags. */
+    tags: Tag[];
+    /** Its dataset's (eval set's) tags. */
+    evalSetTags: Tag[];
+}
+/** The colors a tag can take. */
+export type TagColor = "default" | "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red";
+/** A project's tag: a named, colored label that groups datasets, scorers and experiments. */
+export interface Tag {
+    /** Tag ID. */
+    id: string;
+    /** Name, unique in the project without case. */
+    name: string;
+    /** Display color. */
+    color: TagColor;
+}
 /** A dataset and its versions. */
 export interface Dataset extends Identity {
     /** Dataset ID. */
     id: string;
     /** Archive timestamp on current servers; absent on older compatible responses. */
     archivedAt?: string | null;
+    /** The dataset's tags on servers that support tags; absent on older responses. */
+    tags?: Tag[];
     /** Versions of this dataset. */
     versions: DatasetVersion[];
 }
@@ -139,11 +179,15 @@ export type MetricDefinition = {
     name: string;
     /** Boolean or free-text metric. */
     type: "boolean" | "text";
+    /** What the metric checks, shown with its check in Hue's run view (1–500 characters). */
+    description?: string;
 } | {
     /** Metric name. */
     name: string;
     /** Numeric metric. */
     type: "number";
+    /** What the metric checks, shown with its check in Hue's run view (1–500 characters). */
+    description?: string;
     /** Inclusive lower bound. */
     min?: number;
     /** Inclusive upper bound. */
@@ -153,6 +197,8 @@ export type MetricDefinition = {
     name: string;
     /** Categorical metric. */
     type: "category";
+    /** What the metric checks, shown with its check in Hue's run view (1–500 characters). */
+    description?: string;
     /** Allowed values. */
     categories: string[];
 };
@@ -229,6 +275,25 @@ export type ScorerDefinition = {
         /** The judge every case scored by this version uses. */
         judge: OutcomeJudgeConfig;
     };
+} | {
+    /** A case's reviewed assertions, scored inside Hue from gateway evidence. */
+    kind: "world_outcome";
+    /** Versioned gateway-ledger assertion semantics. */
+    entry: "hue.outcome_assertions.v4" | "hue.outcome_assertions.v5" | "hue.outcome_assertions.v6";
+    /** `task_success` and the fixed assertion counts defined by the entry. */
+    metrics: MetricDefinition[];
+} | {
+    /** An answer-only case, scored inside Hue without world evidence. */
+    kind: "world_outcome";
+    /** Versioned answer semantics; the pinned judge is required to decide the case. */
+    entry: "hue.answer_outcome.v1" | "hue.answer_outcome.v2";
+    /** The assertion and judge counts defined by the entry. */
+    metrics: MetricDefinition[];
+    /** The judge pin used to score the answer. */
+    config: {
+        /** The required judge every case scored by this version uses. */
+        judge: OutcomeJudgeConfig;
+    };
 } | {
     /** Scored by a person in Hue; the local runner defers it. */
     kind: "manual";
@@ -397,6 +462,8 @@ export interface Scorer extends Identity {
     id: string;
     /** Archive timestamp on current servers; absent on older compatible responses. */
     archivedAt?: string | null;
+    /** The scorer's tags on servers that support tags; absent on older responses. */
+    tags?: Tag[];
     /** Published versions, when included in the response. */
     versions?: ScorerVersion[];
 }
@@ -486,6 +553,10 @@ export interface Experiment {
     name: string;
     /** Frozen dataset version under test. */
     datasetVersionId: string;
+    /** The experiment's own tags on servers that support tags; absent on older responses. */
+    tags?: Tag[];
+    /** Its dataset's tags, which tag filters match as well; absent on older responses. */
+    evalSetTags?: Tag[];
     /** Configuration handed to the target. */
     config: JsonValue;
     /** Digest of `config`. */

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.13.0";
+export declare const sdkVersion = "0.13.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.13.0";
+export const sdkVersion = "0.13.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "private": false,
   "license": "MIT",
   "publishConfig": {