@hue-run/sdk 0.11.1 → 0.11.3

package/dist/evals/checkpoint.d.ts

@@ -1,3 +1,8 @@
+/** A server- or user-provided identifier that is safe as a single checkpoint path component:
+ * no separators, no `.`/`..`, and it stays directly inside the directory it is joined onto. */
+export declare function checkpointSegment(value: string, label: string): string;
+/** `join(directory, ...segments)` after validating every segment. */
+export declare function checkpointPath(directory: string, ...segments: [string, string][]): string;
 /** 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 {

package/dist/evals/checkpoint.js

@@ -1,10 +1,26 @@
 import { constants, rmSync } from "node:fs";
 import { lstat, mkdir, open, rename, rm } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { onForcedExit } from "./exit-cleanup.js";
 import { digest } from "./json.js";
 const CONTENT_POLICY = ["persistResultContent", "captureContent"];
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** A server- or user-provided identifier that is safe as a single checkpoint path component:
+ * no separators, no `.`/`..`, and it stays directly inside the directory it is joined onto. */
+export function checkpointSegment(value, label) {
+    if (typeof value !== "string" || !SEGMENT.test(value))
+        throw new Error(`Refusing to use ${label} ${JSON.stringify(value)} in a checkpoint path`);
+    return value;
+}
+/** `join(directory, ...segments)` after validating every segment. */
+export function checkpointPath(directory, ...segments) {
+    const root = resolve(directory);
+    const path = resolve(root, ...segments.map(([value, label]) => checkpointSegment(value, label)));
+    if (path !== root && !path.startsWith(root.endsWith(sep) ? root : root + sep))
+        throw new Error("Checkpoint path escapes its directory");
+    return path;
+}
 /** 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 {

package/dist/evals/client.d.ts

@@ -44,7 +44,8 @@ export declare class EvaluationClient {
     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. */
+     * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
+     * each attempt, and a wait to send one again, whose refusal is then the caller's error. */
     private send;
     private request;
     /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size.
@@ -170,8 +171,10 @@ export declare class EvaluationClient {
     revokeAttemptConnection(input: {
         bindingId: string;
     }): Promise<import("./attempt.js").RevokeAttemptResult>;
-    /** Reads one artifact reservation and its verification state. */
-    getArtifact(id: string): Promise<ArtifactReservation>;
+    /** Reads one artifact reservation and its verification state. `signal` ends the request. */
+    getArtifact(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactReservation>;
     /** Reserves an artifact by declared identity; replaying the key returns the same reservation. */
     reserveArtifact(input: {
         /** Stable key; replaying it returns the same reservation. */
@@ -187,8 +190,11 @@ export declare class EvaluationClient {
     }): Promise<ArtifactReservation>;
     /** Issues a short-lived storage capability for staging the reserved artifact's bytes. */
     requestArtifactUpload(id: string): Promise<ArtifactUpload>;
-    /** Asks Hue to verify the staged bytes against the declared identity. */
-    completeArtifact(id: string): Promise<ArtifactReservation>;
+    /** Asks Hue to verify the staged bytes against the declared identity. `signal` ends the
+     * request, and a wait to send it again. */
+    completeArtifact(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactReservation>;
     /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id: string, input: CompleteExecution): Promise<Completion>;
     /** Marks an experiment finished. */

package/dist/evals/client.js

@@ -149,12 +149,15 @@ export class EvaluationClient {
         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) {
+     * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
+     * each attempt, and a wait to send one again, whose refusal is then the caller's error. */
+    async send(url, init, signal) {
         for (let attempt = 0;; attempt++) {
             let response;
             try {
-                response = await fetch(url, init());
+                const attemptInit = init();
+                const signals = [attemptInit.signal, signal].filter((item) => !!item);
+                response = await fetch(url, { ...attemptInit, signal: AbortSignal.any(signals) });
             }
             catch {
                 throw new HueApiError();
@@ -164,10 +167,23 @@ export class EvaluationClient {
                 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)));
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", done);
+                    resolve();
+                };
+                const timer = setTimeout(done, seconds * 1000 * (1 + Math.random() * 0.5));
+                signal?.addEventListener("abort", done, { once: true });
+                // The signal may have ended while the refusal's body was cancelled.
+                if (signal?.aborted)
+                    done();
+            });
+            if (signal?.aborted)
+                throw new HueApiError(response.status, askedRetryAfter(response));
         }
     }
-    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }) {
+    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }, signal) {
         // Optional top-level fields are omitted intentionally; nested undefined remains invalid.
         const payload = body === undefined
             ? undefined
@@ -181,7 +197,7 @@ export class EvaluationClient {
             body: payload,
             redirect: "error",
             signal: AbortSignal.timeout(this.timeoutMillis),
-        }));
+        }), signal);
         if (!response.ok) {
             await response.body?.cancel();
             throw new HueApiError(response.status, askedRetryAfter(response));
@@ -503,9 +519,9 @@ export class EvaluationClient {
             throw new HueApiError();
         }
     }
-    /** Reads one artifact reservation and its verification state. */
-    getArtifact(id) {
-        return this.request("GET", `/artifacts/${uuid(id)}`);
+    /** Reads one artifact reservation and its verification state. `signal` ends the request. */
+    getArtifact(id, options = {}) {
+        return this.request("GET", `/artifacts/${uuid(id)}`, undefined, undefined, options.signal);
     }
     /** Reserves an artifact by declared identity; replaying the key returns the same reservation. */
     reserveArtifact(input) {
@@ -515,9 +531,10 @@ export class EvaluationClient {
     requestArtifactUpload(id) {
         return this.request("POST", `/artifacts/${uuid(id)}/upload`, {});
     }
-    /** Asks Hue to verify the staged bytes against the declared identity. */
-    completeArtifact(id) {
-        return this.request("POST", `/artifacts/${uuid(id)}/complete`, {});
+    /** Asks Hue to verify the staged bytes against the declared identity. `signal` ends the
+     * request, and a wait to send it again. */
+    completeArtifact(id, options = {}) {
+        return this.request("POST", `/artifacts/${uuid(id)}/complete`, {}, undefined, options.signal);
     }
     /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id, input) {

package/dist/evals/files.js

@@ -339,21 +339,33 @@ function mayStillVerify(error) {
  * a pause: ready is returned; verifying is completed again, which Hue refuses while its lease
  * holds and restarts once it lapsed; an artifact a retryable refusal (a lost response, 429 or 503)
  * left unverified is completed again up to three times; any other state is returned for the
- * caller to refuse (a resume uploads a rejected artifact again). All within `timing.settleMillis`.
+ * caller to refuse (a resume uploads a rejected artifact again). All within `timing.settleMillis`,
+ * which also ends a request in flight and the client's own wait to send one again.
  */
 async function settleArtifact(client, id, timing) {
     const deadline = Date.now() + timing.settleMillis;
+    const signal = AbortSignal.timeout(timing.settleMillis);
+    // The last state read, which names the state when the deadline cuts off a request at it.
+    let known;
+    const timedOut = (last) => {
+        const seconds = Math.round(timing.settleMillis / 1000);
+        return new Error(last?.state === "verifying"
+            ? `Hue was still verifying generated file ${id} after ${seconds} seconds`
+            : `Hue had not verified generated file ${id} after ${seconds} seconds (${last ? `it was ${last.state}` : "its state could not be read"})`);
+    };
     let pause = timing.pollMillis;
     let retries = 0;
     for (;;) {
         let refusedForNow;
         let asked = 0;
         try {
-            return (await client.completeArtifact(id)).state;
+            return (await client.completeArtifact(id, { signal })).state;
         }
         catch (error) {
-            if (!mayStillVerify(error) || Date.now() >= deadline)
+            if (!mayStillVerify(error))
                 throw error;
+            if (Date.now() >= deadline)
+                throw timedOut(known);
             refusedForNow = error.status !== 409;
             // A refusal that says how long to wait is waited out, within the settling window.
             asked = (error.retryAfterSeconds ?? 0) * 1000;
@@ -362,7 +374,7 @@ async function settleArtifact(client, id, timing) {
         pause = Math.min(pause * 2, timing.maxPollMillis);
         let current;
         try {
-            current = await client.getArtifact(id);
+            current = known = await client.getArtifact(id, { signal });
         }
         catch (error) {
             if (!mayStillVerify(error))
@@ -375,12 +387,8 @@ async function settleArtifact(client, id, timing) {
             current.failureCode !== "mismatch";
         if (current && current.state !== "verifying" && !(unverified && refusedForNow && retries++ < 3))
             return current.state;
-        if (Date.now() >= deadline) {
-            const seconds = Math.round(timing.settleMillis / 1000);
-            throw new Error(current?.state === "verifying"
-                ? `Hue was still verifying generated file ${id} after ${seconds} seconds`
-                : `Hue had not verified generated file ${id} after ${seconds} seconds (${current ? `it was ${current.state}` : "its state could not be read"})`);
-        }
+        if (Date.now() >= deadline)
+            throw timedOut(current ?? known);
     }
 }
 /**

package/dist/evals/local-worker.js

@@ -1,6 +1,6 @@
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { CheckpointStore } from "./checkpoint.js";
+import { CheckpointStore, checkpointPath, checkpointSegment } from "./checkpoint.js";
 import { pinRequestedAttemptV2, requestedAttemptV2, runEnvironmentTarget, } from "./environment-target.js";
 import { runExperiment, OutcomeSerializationError, TargetOutcomeUncertainError, UncertainExecutionError, } from "./runner.js";
 /** Capability strings a registration declares; Hue offers only matching cases. */
@@ -159,14 +159,18 @@ export async function runLocalAgent(options) {
             }, Math.min(15_000, Math.max(1_000, interval)));
             let experimentFinished = false;
             try {
+                const experimentId = checkpointSegment(claim.experimentId, "experiment id");
                 const requested = requestedConfiguration
-                    ? pinRequestedAttemptV2(requestedConfiguration, (await options.client.getExperiment(claim.experimentId)).config)
+                    ? pinRequestedAttemptV2(requestedConfiguration, (await options.client.getExperiment(experimentId)).config)
                     : undefined;
                 const report = await runExperiment({
                     client: options.client,
                     hue: options.hue,
-                    experimentId: claim.experimentId,
-                    checkpointDirectory: join(directory, `experiment-${claim.experimentId}`),
+                    experimentId,
+                    checkpointDirectory: checkpointPath(directory, [
+                        `experiment-${experimentId}`,
+                        "experiment id",
+                    ]),
                     persistResultContent: true,
                     // Worker dispatch uses the case pin: directTarget never receives a world.
                     environmentEvidence: options.directTarget ? "when_pinned" : "required",

package/dist/evals/simulation.js

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { join } from "node:path";
 import { HueEnvironmentError } from "../environment/client.js";
 import { HueApiError } from "./client.js";
-import { CheckpointStore } from "./checkpoint.js";
+import { CheckpointStore, checkpointPath, checkpointSegment } from "./checkpoint.js";
 import { MAX_ENVIRONMENT_STEPS } from "./environment-evidence.js";
 import { aggregateBounds, digest, json } from "./json.js";
 import { normalizeScorerDefinitionForPublication } from "./scorer-publication.js";
@@ -404,7 +403,7 @@ export async function runSimulation(options) {
         let bindings = options.localScorers ?? [];
         if (!attempt.experimentId) {
             const resolved = await resolveExperiment(options, definition, attempt.idempotencyKey);
-            attempt.experimentId = resolved.experimentId;
+            attempt.experimentId = checkpointSegment(resolved.experimentId, "experiment id");
             bindings = resolved.bindings;
             attempt.stage = "running";
             await store.write("active-attempt", attempt);
@@ -417,7 +416,7 @@ export async function runSimulation(options) {
                 ...(options.localScorers ?? []),
             ];
         }
-        const experimentId = attempt.experimentId;
+        const experimentId = checkpointSegment(attempt.experimentId, "experiment id");
         const runUrl = new URL(`/experiments/${experimentId}`, options.client.baseUrl).toString();
         await options.onProgress?.({ type: "run_created", experimentId, runUrl });
         const requested = requestedConfiguration
@@ -427,7 +426,10 @@ export async function runSimulation(options) {
             client: options.client,
             hue: options.hue,
             experimentId,
-            checkpointDirectory: join(store.directory, `experiment-${experimentId}`),
+            checkpointDirectory: checkpointPath(store.directory, [
+                `experiment-${experimentId}`,
+                "experiment id",
+            ]),
             persistResultContent: options.persistResultContent,
             traceEvidence: options.traceEvidence,
             ...(options.traceNotAccepted ? { traceNotAccepted: options.traceNotAccepted } : {}),

package/dist/provider-tools.d.ts

@@ -31,7 +31,9 @@ export interface HostedToolActivity {
 /**
  * A provider's error text as a failed call exports it under content capture: credentials
  * scrubbed first, then at most 1,024 code points with `…` marking a cut, lone surrogates
- * replaced and NUL removed. The Python SDK produces the same text.
+ * replaced and NUL removed. Only the first 16,384 code points are scrubbed, and what that cut
+ * interrupts (a quoted value, a URL, a prefixed token) is redacted to it. The Python SDK
+ * produces the same text.
  */
 export declare function providerErrorDescription(value: string): string;
 /**

package/dist/provider-tools.js

@@ -74,11 +74,13 @@ function codePoints(text, count) {
 /**
  * A provider's error text as a failed call exports it under content capture: credentials
  * scrubbed first, then at most 1,024 code points with `…` marking a cut, lone surrogates
- * replaced and NUL removed. The Python SDK produces the same text.
+ * replaced and NUL removed. Only the first 16,384 code points are scrubbed, and what that cut
+ * interrupts (a quoted value, a URL, a prefixed token) is redacted to it. The Python SDK
+ * produces the same text.
  */
 export function providerErrorDescription(value) {
     const scanned = codePoints(value.toWellFormed().replaceAll("\u0000", ""), MAX_ERROR_SCAN);
-    const bounded = codePoints(scrubCredentialText(scanned.text), MAX_ERROR_TEXT);
+    const bounded = codePoints(scrubCredentialText(scanned.text, scanned.cut), MAX_ERROR_TEXT);
     return bounded.cut || scanned.cut ? `${bounded.text}…` : bounded.text;
 }
 /** An OpenAI MCP call's `error`: its text, or an error object's string `message`. */

package/dist/tool-definitions.d.ts

@@ -1,3 +1,6 @@
+/** Whether a field name names a credential: one of `credentialKeys`, or a name ending in `token`,
+ * `secret`, `password`, `apikey` or `credential`, ignoring case, `-` and `_`. */
+export declare function isCredentialKey(key: string): boolean;
 /**
  * Removes credentials from free text a provider returned, such as an MCP call's error message,
  * with the rules tool definitions use, extended for text: each `http`, `https`, `ws`, `wss` or
@@ -6,10 +9,18 @@
  * becomes `[redacted]` when it has an `@`, `?` or `#`; a token with a known credential prefix
  * (`hue_sk_`, `sk-`, `xoxb-`, `ya29.` and others), the credential after an authorization scheme
  * (`Bearer`, `Basic`, `Token`), the whole value of an `Authorization` header, and the value of a
- * `key=value` or `key: value` pair whose key names a credential (quoted, escaped-quoted or bare)
- * become `[redacted]`.
+ * `key=value`, `key: value` or `key => value` pair whose key names a credential (quoted,
+ * escaped-quoted, bare, or a whole `[…]` or `{…}`) become `[redacted]`. A JSON or `%` escape
+ * (`\n`, `\u0022`, `%20`) ends a word as a space does. A quote that does not close on its line
+ * runs to the end of the line, and a URL's quoted query value is replaced whole. `cut` says the
+ * text was cut from a longer one, so a URL or prefixed token that runs to its end is replaced
+ * whole, as is the word of scheme characters it ends in, which may start a URL's scheme. Only the
+ * first 16,384 code points are read: a longer text is cut there, and `…` marks it.
  */
-export declare function scrubCredentialText(text: string): string;
+export declare function scrubCredentialText(text: string, cut?: boolean): string;
+/** `scrubCredentialText` without its bound on the text's length, for tests that time long texts;
+ * callers use `scrubCredentialText`. */
+export declare function scrubCredentialTextUnbounded(text: string, cut?: boolean): string;
 /**
  * Removes hosted-tool credentials from an exported attribute value, before the caller's `redact`.
  * Tool definitions come from OpenTelemetry GenAI (`gen_ai.tool.definitions`), AI SDK 6