@hue-run/sdk 0.11.2 → 0.11.4

package/dist/environment/world.d.ts

@@ -23,10 +23,12 @@ export interface AgentEnvironmentOptions {
      * default; the canonical carriers are the world's own `env`. */
     legacyMcpVariables?: boolean;
 }
+/** `environment` without any variable a world or its server owns. */
+export declare function withoutWorldVariables(environment: Record<string, string>): Record<string, string>;
 /**
  * The environment for an agent child process running one case (the coordination briefs'
- * recommended policy): the parent's variables minus Hue control-plane credentials, then the
- * world's carriers, which win over anything the parent set. Nothing here is logged.
+ * recommended policy): the parent's variables minus Hue control-plane credentials and any
+ * world-scoped variable, then the world's carriers. Nothing here is logged.
  */
 export declare function agentEnvironment(world: WorldHandoff, options?: AgentEnvironmentOptions): Record<string, string>;
 /** The `{ url, token, expiresAt }` shape the `hue_sim_` capability had, projected from the

package/dist/environment/world.js

@@ -53,16 +53,25 @@ export function stripHueControlPlaneCredentials(parent) {
     }
     return child;
 }
+/** Variables a world or its server owns: a parent's value belongs to another world (a runner
+ * started inside a case, a shell left from an earlier run) or to the server (a signing key), and
+ * would send this world's token to a mirror this world does not have. The whole `HUE_WORLD_`
+ * prefix is the world's. */
+const WORLD_SCOPED = /^(?:HUE_WORLD_[A-Z0-9_]+|HUE_MCP_(?:CONFIG|URL|TOKEN|EXPIRES_AT)|HUE_SIM_[A-Z0-9_]+_(?:URL|ALIAS))$/;
+/** `environment` without any variable a world or its server owns. */
+export function withoutWorldVariables(environment) {
+    return Object.fromEntries(Object.entries(environment).filter(([name]) => !WORLD_SCOPED.test(name)));
+}
 /**
  * The environment for an agent child process running one case (the coordination briefs'
- * recommended policy): the parent's variables minus Hue control-plane credentials, then the
- * world's carriers, which win over anything the parent set. Nothing here is logged.
+ * recommended policy): the parent's variables minus Hue control-plane credentials and any
+ * world-scoped variable, then the world's carriers. Nothing here is logged.
  */
 export function agentEnvironment(world, options = {}) {
     const parent = options.parent ?? process.env;
-    const child = options.includeHueCredentials
+    const child = withoutWorldVariables(options.includeHueCredentials
         ? Object.fromEntries(Object.entries(parent).filter((entry) => entry[1] !== undefined))
-        : stripHueControlPlaneCredentials(parent);
+        : stripHueControlPlaneCredentials(parent));
     Object.assign(child, world.env);
     if (options.legacyMcpVariables ?? true) {
         const legacy = legacyMcpCapability(world);

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