@hue-run/sdk 0.8.1 → 0.10.0

package/dist/client.js

@@ -40,7 +40,7 @@ function identifier(value) {
         throw new TypeError("Session/user/workspace identifiers must contain 1–4096 valid characters");
     return value;
 }
-/** A usable metadata label: a non-blank string of at most 256 characters. */
+/** A usable metadata label: non-blank, at most 256 UTF-16 code units, with no NUL or unpaired surrogate. */
 function isLabel(value) {
     return (typeof value === "string" &&
         value.trim() !== "" &&
@@ -48,18 +48,6 @@ function isLabel(value) {
         !value.includes("\u0000") &&
         value.isWellFormed());
 }
-/** A source label uses the stricter wire-safe validation without changing existing labels. */
-function isSourceLabel(value) {
-    return (typeof value === "string" &&
-        value.trim() !== "" &&
-        value.length <= 256 &&
-        !value.includes("\u0000") &&
-        value.isWellFormed());
-}
-/** A label that is also free of NUL and unpaired surrogates, which export would reject. */
-function isTextLabel(value) {
-    return isLabel(value) && !value.includes("\u0000") && value.isWellFormed();
-}
 /**
  * Runs `work` exactly once with `active` as OpenTelemetry's current context, so instrumentations
  * that use the global API parent under the Hue span. Without a registered context manager
@@ -330,11 +318,11 @@ export class HueClient {
             "gen_ai.operation.name": "execute_tool",
             "gen_ai.tool.name": name,
         };
-        const stamp = (key, value, valid = isLabel) => {
+        const stamp = (key, value) => {
             if (value === undefined)
                 return;
             // A blank or non-string label is omitted and counted; the tool call itself still runs.
-            if (valid(value))
+            if (isLabel(value))
                 attributes[key] = value;
             else if (this.enabled && !this.closed)
                 this.transport.instrumentationFailure();
@@ -342,8 +330,8 @@ export class HueClient {
         stamp("gen_ai.tool.call.id", options.callId);
         stamp("mcp.server.name", options.mcp?.name);
         stamp("mcp.server.version", options.mcp?.version);
-        stamp("hue.mcp.provider", options.mcp?.provider, isSourceLabel);
-        stamp("hue.mcp.surface", options.mcp?.surface, isSourceLabel);
+        stamp("hue.mcp.provider", options.mcp?.provider);
+        stamp("hue.mcp.surface", options.mcp?.surface);
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
@@ -555,7 +543,9 @@ export class HueClient {
                 const attributes = {};
                 if (label === undefined)
                     return attributes;
-                const info = options.servers?.[label];
+                const info = options.servers && Object.hasOwn(options.servers, label)
+                    ? options.servers[label]
+                    : undefined;
                 for (const [key, value] of [
                     ["mcp.server.name", info?.name ?? label],
                     ["mcp.server.version", info?.version],
@@ -630,7 +620,7 @@ export class HueClient {
             const { role, mediaType, data, name } = file;
             if (role !== "input" && role !== "attachment" && role !== "output")
                 throw new TypeError("Invalid file role");
-            if (!isTextLabel(mediaType))
+            if (!isLabel(mediaType))
                 throw new TypeError("Invalid media type");
             let sha256 = typeof file.sha256 === "string" ? file.sha256.toLowerCase() : file.sha256;
             let byteSize = file.byteSize;
@@ -673,7 +663,7 @@ export class HueClient {
             if (byteSize !== undefined)
                 attributes["hue.file.size"] = byteSize;
             if (this.captureContent && name !== undefined) {
-                if (isTextLabel(name))
+                if (isLabel(name))
                     attributes["hue.file.name"] = name;
                 else
                     this.transport.instrumentationFailure();

package/dist/environment/client.d.ts

@@ -16,12 +16,18 @@ export declare class HueEnvironmentError extends Error {
     readonly status?: number | undefined;
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
     readonly retryAfterMs?: number | undefined;
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    readonly diagnostic?: string | undefined;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     status?: number | undefined, 
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
-    retryAfterMs?: number | undefined);
+    retryAfterMs?: number | undefined, 
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    diagnostic?: string | undefined);
 }
+/** A connection failure or a status the client retries; seal polling continues through these. */
+export declare function isTransientEnvironmentError(error: unknown): boolean;
 /** Typed client for authored environments, isolated runs and immutable journals. */
 export declare class EnvironmentClient {
     /** Validated Hue origin. */
@@ -47,7 +53,9 @@ export declare class EnvironmentClient {
     /** Creates or recovers one fresh isolated world using a stable idempotency key. */
     createRun(input: CreateRunInput): Promise<EnvironmentRun>;
     /** Reads authoritative current or sealed world state. */
-    getRun(runId: string): Promise<{
+    getRun(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
         id: string;
         environmentVersionId: string;
         executionId: string | null;

package/dist/environment/client.js

@@ -4,20 +4,35 @@ import { aggregateBounds, json, uuid, valueBounds } from "../evals/json.js";
 export class HueEnvironmentError extends Error {
     status;
     retryAfterMs;
+    diagnostic;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     status, 
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
-    retryAfterMs) {
+    retryAfterMs, 
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    diagnostic) {
         super(status
-            ? `Hue environment request failed (HTTP ${status})`
+            ? `Hue environment request failed (HTTP ${status}${diagnostic ? `, ${diagnostic}` : ""})`
             : "Hue environment connection or response failed");
         this.status = status;
         this.retryAfterMs = retryAfterMs;
+        this.diagnostic = diagnostic;
         this.name = "HueEnvironmentError";
     }
 }
+const DIAGNOSTIC = /^[a-z_]{1,64}$/;
+/** The response's diagnostic code, or undefined when absent or invalid. */
+function diagnosticOf(response) {
+    const value = response.headers.get("x-hue-diagnostic");
+    return value !== null && DIAGNOSTIC.test(value) ? value : undefined;
+}
 const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+/** A connection failure or a status the client retries; seal polling continues through these. */
+export function isTransientEnvironmentError(error) {
+    return (error instanceof HueEnvironmentError &&
+        (error.status === undefined || RETRYABLE.has(error.status)));
+}
 /** A `Retry-After` longer than this waits this long: Hue asks for a second, never minutes. */
 const MAX_RETRY_AFTER_MS = 10_000;
 const TRACEPARENT = /^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
@@ -64,9 +79,10 @@ export class EnvironmentClient {
             throw new RangeError("maxAttempts must be 1–10");
         this.maxAttempts = attempts;
     }
-    async send(method, path, payload) {
+    async send(method, path, payload, options = {}) {
         let response;
         try {
+            const timeout = AbortSignal.timeout(this.timeoutMillis);
             response = await fetch(`${this.baseUrl}/api/v1${path}`, {
                 method,
                 headers: {
@@ -75,7 +91,7 @@ export class EnvironmentClient {
                 },
                 body: payload,
                 redirect: "error",
-                signal: AbortSignal.timeout(this.timeoutMillis),
+                signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
             });
         }
         catch {
@@ -83,7 +99,7 @@ export class EnvironmentClient {
         }
         if (!response.ok) {
             await response.body?.cancel();
-            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined);
+            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined, diagnosticOf(response));
         }
         try {
             const reader = response.body?.getReader();
@@ -111,25 +127,40 @@ export class EnvironmentClient {
             throw new HueEnvironmentError();
         }
     }
-    async request(method, path, body) {
+    async request(method, path, body, options = {}) {
         // Serialize once: a body this client cannot encode is a caller error that no retry fixes.
         const payload = body === undefined
             ? undefined
             : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), REQUEST_BOUNDS));
         for (let attempt = 1;; attempt++) {
             try {
-                return await this.send(method, path, payload);
+                return await this.send(method, path, payload, options);
             }
             catch (error) {
                 if (!(error instanceof HueEnvironmentError))
                     throw error;
-                const recoverable = error.status === undefined || RETRYABLE.has(error.status);
-                if (!recoverable || attempt >= this.maxAttempts)
+                if (options.signal?.aborted)
+                    throw error;
+                if (!isTransientEnvironmentError(error) || attempt >= this.maxAttempts)
                     throw error;
                 // Hue's admission refusals say how long to wait; anything else backs off.
                 const backoff = Math.min(100 * 2 ** (attempt - 1), 2000);
                 const wait = error.retryAfterMs ?? backoff + Math.random() * backoff;
-                await new Promise((resolve) => setTimeout(resolve, wait));
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        options.signal?.removeEventListener("abort", abort);
+                        resolve();
+                    }, wait);
+                    const abort = () => {
+                        clearTimeout(timer);
+                        options.signal?.removeEventListener("abort", abort);
+                        reject(new HueEnvironmentError());
+                    };
+                    if (options.signal?.aborted)
+                        abort();
+                    else
+                        options.signal?.addEventListener("abort", abort, { once: true });
+                });
             }
         }
     }
@@ -194,8 +225,8 @@ export class EnvironmentClient {
         });
     }
     /** Reads authoritative current or sealed world state. */
-    async getRun(runId) {
-        const run = await this.request("GET", `/environment-runs/${uuid(runId)}`);
+    async getRun(runId, options = {}) {
+        const run = await this.request("GET", `/environment-runs/${uuid(runId)}`, undefined, options);
         return { validity: "not_assessed", coverageGap: null, ...run };
     }
     /** Record a known coverage gap with durable identity; retries reuse the exact request. */

package/dist/environment/types.d.ts

@@ -173,6 +173,35 @@ export interface EnvironmentDefinition {
 /** The extendable legacy name remains V1. Publication and runs select their
  * explicit version; provider context is validated by the authoritative server. */
 export type EnvironmentDefinitionV1 = EnvironmentDefinition;
+/** Gmail mailbox carrier holding messages and drafts in the simplified shape Hue's
+ * `hue.gmail.*` actions read. */
+export interface GmailMailboxConfigurationV1 {
+    /** Gmail mailbox configuration discriminator. */
+    kind: "gmail_mailbox/v1";
+    /** Collection containing synthetic messages. */
+    messagesCollection: string;
+    /** Collection containing synthetic drafts. */
+    draftsCollection: string;
+    /** Synthetic mailbox address. */
+    mailboxAddress: string;
+}
+/** Gmail mailbox carrier served by Hue's simulation gateway: messages, drafts and labels in the
+ * entity shapes the Gmail mirrors serve, with threads derived from each message's `threadId`. A
+ * definition whose provider instances all use it may publish with no actions. */
+export interface GmailMailboxConfigurationV2 {
+    /** Gmail mailbox configuration discriminator. */
+    kind: "gmail_mailbox/v2";
+    /** Collection containing synthetic messages. */
+    messagesCollection: string;
+    /** Collection containing synthetic drafts, each naming a `DRAFT`-labelled message. */
+    draftsCollection: string;
+    /** Collection containing synthetic labels. */
+    labelsCollection: string;
+    /** Synthetic mailbox address; Hue accepts only `owner@example.test`, in any letter case. */
+    mailboxAddress: string;
+}
+/** Either Gmail mailbox carrier, discriminated by `kind`; Hue validates both at publication. */
+export type GmailMailboxConfiguration = GmailMailboxConfigurationV1 | GmailMailboxConfigurationV2;
 /** One synthetic Gmail principal and its world-state collection bindings. */
 export interface GmailProviderInstance {
     /** Stable instance key referenced by attempt provider selection. */
@@ -182,16 +211,7 @@ export interface GmailProviderInstance {
     /** Synthetic principal UUID, canonicalized to lowercase by Hue. */
     syntheticPrincipalId: string;
     /** Versioned mapping from Gmail concepts to authored-world collections. */
-    configuration: {
-        /** Gmail mailbox configuration discriminator. */
-        kind: "gmail_mailbox/v1";
-        /** Collection containing synthetic messages. */
-        messagesCollection: string;
-        /** Collection containing synthetic drafts. */
-        draftsCollection: string;
-        /** Synthetic mailbox address. */
-        mailboxAddress: string;
-    };
+    configuration: GmailMailboxConfiguration;
 }
 /** V2 authored world with immutable provider-instance bindings. */
 export interface EnvironmentDefinitionV2 extends Omit<EnvironmentDefinition, "schemaVersion"> {

package/dist/environment.d.ts

@@ -1,4 +1,4 @@
-export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, } from "./environment/client.js";
+export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./environment/client.js";
 export type { EnvironmentClientOptions } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
 export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./environment/tools.js";

package/dist/environment.js

@@ -1,3 +1,3 @@
-export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, } from "./environment/client.js";
+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";

package/dist/evals/checkpoint.d.ts

@@ -1,6 +1,20 @@
-/** One owner per directory. A crash leaves .lock for explicit operator recovery. */
+/** The checkpoint belongs to a run started with a different identity. When only its content
+ * policy differs, `startedWith` holds the policy the unfinished run was started with. */
+export declare class CheckpointIdentityError extends Error {
+    readonly startedWith?: {
+        persistResultContent?: unknown;
+        captureContent?: unknown;
+    } | undefined;
+    constructor(startedWith?: {
+        persistResultContent?: unknown;
+        captureContent?: unknown;
+    } | undefined);
+}
+/** One owner per directory. A crash leaves .lock for explicit operator recovery; a forced exit of
+ * `hue eval`, which stops its agents first, releases it. */
 export declare class CheckpointStore {
     readonly directory: string;
+    private untrack;
     private constructor();
     static acquire(directory: string, identity: unknown): Promise<CheckpointStore>;
     read<T>(key: string): Promise<T | undefined>;

package/dist/evals/checkpoint.js

@@ -1,11 +1,40 @@
-import { constants } from "node:fs";
+import { constants, rmSync } from "node:fs";
 import { lstat, mkdir, open, rename, rm } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
+import { onForcedExit } from "./exit-cleanup.js";
 import { digest } from "./json.js";
-/** One owner per directory. A crash leaves .lock for explicit operator recovery. */
+const CONTENT_POLICY = ["persistResultContent", "captureContent"];
+/** The checkpoint belongs to a run started with a different identity. When only its content
+ * policy differs, `startedWith` holds the policy the unfinished run was started with. */
+export class CheckpointIdentityError extends Error {
+    startedWith;
+    constructor(startedWith) {
+        super(startedWith
+            ? "Checkpoint content policy differs from the one this unfinished run was started with"
+            : "Checkpoint identity differs from this project, run, pins or content policy");
+        this.startedWith = startedWith;
+        this.name = "CheckpointIdentityError";
+    }
+}
+/** The prior policy when two identities differ only in their content policy. */
+function contentPolicyOnly(prior, identity) {
+    if (!prior || !identity || typeof prior !== "object" || typeof identity !== "object")
+        return undefined;
+    const before = prior;
+    const after = identity;
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of keys)
+        if (!CONTENT_POLICY.includes(key) &&
+            JSON.stringify(before[key]) !== JSON.stringify(after[key]))
+            return undefined;
+    return Object.fromEntries(CONTENT_POLICY.map((key) => [key, before[key]]));
+}
+/** One owner per directory. A crash leaves .lock for explicit operator recovery; a forced exit of
+ * `hue eval`, which stops its agents first, releases it. */
 export class CheckpointStore {
     directory;
+    untrack = () => { };
     constructor(directory) {
         this.directory = directory;
     }
@@ -18,6 +47,7 @@ export class CheckpointStore {
         const store = new CheckpointStore(root);
         try {
             await mkdir(join(root, ".lock"), { mode: 0o700 });
+            store.untrack = onForcedExit(() => rmSync(join(root, ".lock"), { recursive: true, force: true }));
         }
         catch {
             throw new Error("Checkpoint directory is locked; confirm its owner stopped before explicitly removing .lock");
@@ -27,7 +57,7 @@ export class CheckpointStore {
             const expected = { format: 1, identity, digest: digest(identity) };
             const prior = await store.read("manifest");
             if (prior && (prior.format !== 1 || prior.digest !== expected.digest))
-                throw new Error("Checkpoint identity differs from this project, run, pins or content policy");
+                throw new CheckpointIdentityError(prior.format === 1 ? contentPolicyOnly(prior.identity, identity) : undefined);
             if (!prior)
                 await store.write("manifest", expected);
             return store;
@@ -85,5 +115,6 @@ export class CheckpointStore {
     }
     async release() {
         await rm(join(this.directory, ".lock"), { recursive: true });
+        this.untrack();
     }
 }

package/dist/evals/client.d.ts

@@ -18,10 +18,20 @@ export declare class HueApiError extends Error {
     /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
     status?: number | undefined);
 }
+/** An artifact download that ran past the size its caller expected; the rest is not read. */
+export declare class ArtifactSizeError extends Error {
+    /** The size the caller expected, in bytes. */
+    readonly maxBytes: number;
+    constructor(
+    /** The size the caller expected, in bytes. */
+    maxBytes: number);
+}
 /**
  * Typed client for Hue's evaluation REST API: datasets, scorers, experiments, executions, runs,
  * results and hosted judge jobs. No implicit mutation retry: callers retain stable idempotency keys
- * for experiments and results. Responses are bounded to 4 MiB.
+ * for experiments and results. The one exception is a request Hue refused before acting on it with
+ * a short `Retry-After` (HTTP 429 or 503, at most 5 seconds): it is sent again after that wait, up
+ * to four times. Responses are bounded to 4 MiB.
  */
 export declare class EvaluationClient {
     /** Validated Hue origin. */
@@ -29,9 +39,15 @@ export declare class EvaluationClient {
     private readonly apiKey;
     private readonly timeoutMillis;
     constructor(options: EvaluationClientOptions);
+    /** Sends one request to Hue, again after the wait while Hue refuses it with a short
+     * `Retry-After`. `init` runs for every attempt, so each has its own timeout. */
+    private send;
     private request;
-    /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size. */
-    downloadArtifact(id: string): Promise<Uint8Array>;
+    /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size.
+     * With `maxBytes`, the download stops one byte past it and throws `ArtifactSizeError`. */
+    downloadArtifact(id: string, options?: {
+        maxBytes?: number;
+    }): Promise<Uint8Array>;
     /** Stage bytes at the storage capability Hue issued. The Hue key is never sent to storage. */
     uploadArtifactBytes(upload: ArtifactUpload, bytes: Uint8Array, contentType: string): Promise<void>;
     private page;

package/dist/evals/client.js

@@ -12,6 +12,17 @@ export class HueApiError extends Error {
         this.name = "HueApiError";
     }
 }
+/** An artifact download that ran past the size its caller expected; the rest is not read. */
+export class ArtifactSizeError extends Error {
+    maxBytes;
+    constructor(
+    /** The size the caller expected, in bytes. */
+    maxBytes) {
+        super(`Artifact download exceeded the expected ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = "ArtifactSizeError";
+    }
+}
 const registryFieldAliases = [
     ["datasetId", "evalSetId"],
     ["datasetVersionId", "evalSetVersionId"],
@@ -91,10 +102,30 @@ function productRunFields(value, kind) {
         result.scoring = result.evaluation;
     return result;
 }
+/** Times a refused request is sent again before its refusal is the caller's error. */
+const REFUSAL_RETRIES = 4;
+/** A refusal asking for a longer wait fails at once rather than holding the caller. */
+const MAX_REFUSAL_RETRY_AFTER_SECONDS = 5;
+/**
+ * The whole-second `Retry-After` of a 429 or 503 asking for at most 5 seconds. Hue sends one only
+ * when it refused the request before acting on it, such as a busy key check, so sending any method
+ * again is safe. A date, a longer wait or any other failure, a timeout included, is not retried.
+ */
+function refusalRetryAfter(response) {
+    if (response.status !== 429 && response.status !== 503)
+        return undefined;
+    const header = response.headers.get("retry-after")?.trim() ?? "";
+    if (!/^\d{1,6}$/.test(header))
+        return undefined;
+    const seconds = Number(header);
+    return seconds <= MAX_REFUSAL_RETRY_AFTER_SECONDS ? seconds : undefined;
+}
 /**
  * Typed client for Hue's evaluation REST API: datasets, scorers, experiments, executions, runs,
  * results and hosted judge jobs. No implicit mutation retry: callers retain stable idempotency keys
- * for experiments and results. Responses are bounded to 4 MiB.
+ * for experiments and results. The one exception is a request Hue refused before acting on it with
+ * a short `Retry-After` (HTTP 429 or 503, at most 5 seconds): it is sent again after that wait, up
+ * to four times. Responses are bounded to 4 MiB.
  */
 export class EvaluationClient {
     /** Validated Hue origin. */
@@ -111,27 +142,40 @@ export class EvaluationClient {
         this.apiKey = validated.apiKey;
         this.timeoutMillis = validated.timeoutMillis;
     }
+    /** Sends one request to Hue, again after the wait while Hue refuses it with a short
+     * `Retry-After`. `init` runs for every attempt, so each has its own timeout. */
+    async send(url, init) {
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await fetch(url, init());
+            }
+            catch {
+                throw new HueApiError();
+            }
+            const seconds = attempt < REFUSAL_RETRIES ? refusalRetryAfter(response) : undefined;
+            if (seconds === undefined)
+                return response;
+            await response.body?.cancel().catch(() => undefined);
+            // Never sooner than asked; the jitter spreads out parallel requests refused together.
+            await new Promise((resolve) => setTimeout(resolve, seconds * 1000 * (1 + Math.random() * 0.5)));
+        }
+    }
     async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }) {
         // Optional top-level fields are omitted intentionally; nested undefined remains invalid.
         const payload = body === undefined
             ? undefined
             : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
-        let response;
-        try {
-            response = await fetch(`${this.baseUrl}/api/v1${path}`, {
-                method,
-                headers: {
-                    Authorization: `Bearer ${this.apiKey}`,
-                    ...(payload ? { "Content-Type": "application/json" } : {}),
-                },
-                body: payload,
-                redirect: "error",
-                signal: AbortSignal.timeout(this.timeoutMillis),
-            });
-        }
-        catch {
-            throw new HueApiError();
-        }
+        const response = await this.send(`${this.baseUrl}/api/v1${path}`, () => ({
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...(payload ? { "Content-Type": "application/json" } : {}),
+            },
+            body: payload,
+            redirect: "error",
+            signal: AbortSignal.timeout(this.timeoutMillis),
+        }));
         if (!response.ok) {
             await response.body?.cancel();
             throw new HueApiError(response.status);
@@ -162,20 +206,18 @@ export class EvaluationClient {
             throw new HueApiError();
         }
     }
-    /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size. */
-    async downloadArtifact(id) {
-        let response;
-        try {
-            response = await fetch(`${this.baseUrl}/api/v1/artifacts/${uuid(id)}/download`, {
-                method: "GET",
-                headers: { Authorization: `Bearer ${this.apiKey}` },
-                redirect: "error",
-                signal: AbortSignal.timeout(Math.max(this.timeoutMillis, 120_000)),
-            });
-        }
-        catch {
-            throw new HueApiError();
-        }
+    /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size.
+     * With `maxBytes`, the download stops one byte past it and throws `ArtifactSizeError`. */
+    async downloadArtifact(id, options = {}) {
+        const expected = options.maxBytes;
+        if (expected !== undefined && (!Number.isSafeInteger(expected) || expected < 0))
+            throw new RangeError("maxBytes must be a non-negative integer");
+        const response = await this.send(`${this.baseUrl}/api/v1/artifacts/${uuid(id)}/download`, () => ({
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+            redirect: "error",
+            signal: AbortSignal.timeout(Math.max(this.timeoutMillis, 120_000)),
+        }));
         if (!response.ok) {
             await response.body?.cancel();
             throw new HueApiError(response.status);
@@ -192,6 +234,8 @@ export class EvaluationClient {
                     if (done)
                         break;
                     size += value.byteLength;
+                    if (expected !== undefined && size > expected)
+                        throw new ArtifactSizeError(expected);
                     if (size > 25 * 1024 * 1024)
                         throw new Error("Oversized artifact");
                     chunks.push(value);
@@ -202,7 +246,9 @@ export class EvaluationClient {
             }
             return new Uint8Array(Buffer.concat(chunks));
         }
-        catch {
+        catch (error) {
+            if (error instanceof ArtifactSizeError)
+                throw error;
             throw new HueApiError();
         }
     }
@@ -592,8 +638,10 @@ export class EvaluationClient {
         return this.request("GET", "/judge-budget");
     }
     /** Register or refresh the fixed local agent key and revision. */
-    registerLocalAgent(input) {
-        return this.request("POST", "/local-agent-worker/register", input);
+    async registerLocalAgent(input) {
+        const agent = await this.request("POST", "/local-agent-worker/register", input);
+        // Hue's response names the key `agentKey`; read either name.
+        return { ...agent, key: agent.key ?? agent.agentKey ?? input.key };
     }
     /** Claim a queued run for this agent and durable worker identity. */
     claimLocalAgentRun(input) {