@hue-run/sdk 0.13.0 → 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.13.0`, `@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.13.0.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.13.0.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,8 +599,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

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

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 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. */

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 the order they were created. */
+    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),
     }),
 ]);

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[];
 };
@@ -397,6 +443,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 +534,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.1";

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.1";

package/package.json

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