@hue-run/sdk 0.20.2 → 0.20.3

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.20.2`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.3`, `@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.
 
@@ -381,8 +381,8 @@ and Hue never receives or stores them. The command is part of the `hue` executab
 #   LANGFUSE_PUBLIC_KEY=pk-lf-...
 #   LANGFUSE_SECRET_KEY=sk-lf-...
 #   LANGFUSE_BASE_URL=https://cloud.langfuse.com
-npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` come from the environment or `--env-path`
@@ -687,7 +687,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.20.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.3.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -698,7 +698,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.20.2.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.3.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -740,10 +740,10 @@ otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`
 production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx -y @hue-run/sdk@0.20.2 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.2 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
-npx -y @hue-run/sdk@0.20.2 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.2 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.20.3 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.20.3 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
+npx -y @hue-run/sdk@0.20.3 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.20.3 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -781,7 +781,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.2 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.3 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/EVALUATIONS.md

@@ -362,7 +362,9 @@ Python SDK's `run_experiment` and `rescore` hand pinned input files to targets a
 generated files and the outbound worker are TypeScript-only.
 
 Since TypeScript 0.13.2, the `hue eval --worker --command "…"` wrapper supplies both callbacks, so one
-command worker accepts direct and world cases, including mixed eval sets. It keeps the launch
+command worker accepts direct and world cases, including mixed eval sets. Since 0.20.3, a one-shot
+`hue eval --set` over such a set runs it as one `mixed` run: each case takes its own kind's path
+under one experiment and its own checkpoint identity (`--mode simulation` over it is refused). It keeps the launch
 directory for relative application entry points; private case inputs/output still use
 `HUE_CASE_*`. An adapter-file worker opts into the direct callback with `--capability direct:v1`
 and must handle `context.mode === "direct"`. Restart an existing environment-only command

package/README.md

@@ -536,8 +536,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3

package/dist/cli/eval.js

@@ -20,7 +20,8 @@ import { describeTelemetryIssues, runExperiment, TargetCancelledError, TELEMETRY
 import { HueExportError } from "../transport.js";
 import { matchByName, parseScenarioSelector, resolveEvalSetPins, resolveScenarioPins, } from "../evals/scenarios.js";
 import { collectDirectOutputs, stageDirectCase } from "./eval-direct.js";
-import { runSimulation, } from "../evals/simulation.js";
+import { runEnvironmentTarget } from "../evals/environment-target.js";
+import { runSimulation, simulationTargetContext, } from "../evals/simulation.js";
 import { collectExperimentVerdicts, compareVerdicts, metricPassed, } from "../evals/verdicts.js";
 import { DEFAULT_ENV_FILE, envFileArgument, envFileOptions } from "./env-file.js";
 const USAGE = `Usage: hue eval [adapter-file] [options]
@@ -35,7 +36,9 @@ Selection (exactly one, not used with --worker):
   --dataset-version <id>          Frozen dataset version; requires --scorer or --scorer-version
   --scorer <slug|name|id>         Evaluator to pin at its latest published version (repeatable)
   --scorer-version <id>           Scorer version to pin (repeatable)
-  --mode <auto|direct|simulation> Case kind; auto picks direct for sets whose cases pin no world
+  --mode <auto|direct|simulation> Case kind; auto picks direct for sets whose cases pin no
+                                  world and runs a set mixing both kinds as one run, each
+                                  case through its own kind's path
 
 Agent (exactly one):
   <adapter-file>                  Module exporting default or runMyAgent(inputs, context)
@@ -979,9 +982,11 @@ function parseMode(value) {
         return value;
     throw new UsageError("--mode must be auto, direct or simulation");
 }
-/** The selection's cases, and whether the run is direct: when `--mode` leaves it open, direct
- * means nothing pins a simulated world, not a Scenario and no case of the version. A simulation
- * run cannot execute a case that pins no world, so a selection mixing both kinds is refused. */
+/** The selection's cases and how they run. When `--mode` leaves it open, a version mixing cases
+ * that pin a world with cases that pin none runs as one mixed run; direct means nothing pins a
+ * simulated world, not a Scenario and no case of the version; anything else is a simulation. A
+ * simulation run cannot execute a case that pins no world, so `--mode simulation` over such
+ * cases is refused. */
 async function inspectSelection(client, pins, mode) {
     let cases = 0;
     let worldCases = 0;
@@ -992,14 +997,18 @@ async function inspectSelection(client, pins, mode) {
         worldCases += page.items.filter((item) => item.environmentVersionId).length;
         after = page.nextCursor ?? undefined;
     } while (after);
-    const direct = mode === "auto"
-        ? !pins.scenarioId && !pins.environmentVersionId && worldCases === 0
-        : mode === "direct";
     const answerOnly = cases - worldCases;
-    const refusal = !direct && answerOnly > 0
-        ? `${answerOnly} of the ${cases} ${cases === 1 ? "case pins" : "cases pin"} no world, so a simulation run would fail ${answerOnly === 1 ? "it" : "them"} before the agent starts. Put the answer-only cases in their own eval set${mode === "simulation" ? ", or drop --mode simulation" : ""}.`
+    const kind = mode !== "auto"
+        ? mode
+        : worldCases > 0 && answerOnly > 0
+            ? "mixed"
+            : worldCases === 0 && !pins.scenarioId && !pins.environmentVersionId
+                ? "direct"
+                : "simulation";
+    const refusal = kind === "simulation" && answerOnly > 0
+        ? `${answerOnly} of the ${cases} ${cases === 1 ? "case pins" : "cases pin"} no world, so a simulation run would fail ${answerOnly === 1 ? "it" : "them"} before the agent starts. ${mode === "simulation" ? "Drop --mode simulation: --mode auto runs the world cases and the answer-only cases together as one run" : "Put the answer-only cases in their own eval set"}.`
         : undefined;
-    return { direct, cases, worldCases, ...(refusal ? { refusal } : {}) };
+    return { kind, cases, worldCases, ...(refusal ? { refusal } : {}) };
 }
 function toJson(verdicts, runUrl, baseline, extra = {}, telemetry = []) {
     const notAccepted = new Map(telemetry.map((entry) => [entry.caseId, entry.issues]));
@@ -1255,7 +1264,9 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
     }
     const runName = values.name ?? defaultRunName(agent);
     const project = await client.checkConnection();
-    const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, selection.direct ? "direct" : "simulation");
+    // Each kind of run has its own checkpoint directory and identity: a mixed run never resumes
+    // from, or is resumed by, a direct or simulation run's checkpoint.
+    const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, selection.kind);
     const judging = values.judges
         ? {
             store: await CheckpointStore.acquire(checkpointPath(checkpointDirectory, ["judge-dispatch", "judge checkpoint"]), { kind: "cli-judge-dispatch", projectId: project.id, baseUrl: connection.baseUrl }),
@@ -1267,7 +1278,7 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
             source: {
                 directory: checkpointDirectory,
                 identity: {
-                    kind: selection.direct ? "direct" : "simulation",
+                    kind: selection.kind,
                     projectId: project.id,
                     baseUrl: connection.baseUrl,
                 },
@@ -1283,8 +1294,9 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
             await completeJudgeHandoff(client, judging, pending);
             return await reportVerdicts(client, values, pending.run, baselineId, output, signal, judging);
         }
-        if (selection.direct)
-            return await runDirect({
+        if (selection.kind !== "simulation")
+            return await runExperimentAttempt({
+                kind: selection.kind,
                 client,
                 values,
                 pins,
@@ -1298,6 +1310,7 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
                 concurrency,
                 baselineId,
                 judging,
+                checkpointDirectory,
             }, connection);
         const environmentClient = createEnvironmentClient(connection);
         const caseKeys = new Map();
@@ -1393,8 +1406,11 @@ async function checkRun(client, values, pins, selection, agent, output) {
             return 1;
         }
     }
-    const { direct, cases, worldCases, refusal } = selection;
+    const { kind, cases, worldCases, refusal } = selection;
     const unsaved = !pins.saved && !values["save-version"];
+    // What each kind of run gives its cases: a direct run gives no case a world, a simulation
+    // run gives every case one (and is refused over cases that pin none), a mixed run gives one
+    // to each case that pins one.
     const check = {
         ok: !unsaved && !refusal,
         project: { id: project.id, name: project.name },
@@ -1406,8 +1422,9 @@ async function checkRun(client, values, pins, selection, agent, output) {
             cases,
             evaluators: pins.scorerVersionIds.length,
         },
-        mode: direct ? "direct" : "simulation",
-        worldCases: direct ? 0 : worldCases,
+        mode: kind,
+        worldCases: kind === "direct" ? 0 : worldCases,
+        directCases: kind === "direct" ? cases : cases - worldCases,
         agent: { key: agent.key, revision: agent.revision, concurrency: values.concurrency ?? "1" },
     };
     if (values.json)
@@ -1415,9 +1432,12 @@ async function checkRun(client, values, pins, selection, agent, output) {
     else {
         output.log(`Project: ${project.name} (${project.id})`);
         output.log(`Selection: ${check.selection.kind === "case" ? "case" : "eval set"} "${pins.name}", ${cases} ${cases === 1 ? "case" : "cases"}, ${pins.scorerVersionIds.length} ${pins.scorerVersionIds.length === 1 ? "evaluator" : "evaluators"}`);
-        output.log(direct
+        const worlds = `${worldCases} ${worldCases === 1 ? "case gets" : "cases get"} a fresh world, reached through the HUE_SIM_*_URL mirrors and HUE_WORLD_TOKEN`;
+        output.log(kind === "direct"
             ? "Mode: direct; the agent answers without a simulated world or app mirrors"
-            : `Mode: simulation; ${worldCases} ${worldCases === 1 ? "case gets" : "cases get"} a fresh world, reached through the HUE_SIM_*_URL mirrors and HUE_WORLD_TOKEN`);
+            : kind === "simulation"
+                ? `Mode: simulation; ${worlds}`
+                : `Mode: mixed; ${worlds}, and ${check.directCases} ${check.directCases === 1 ? "case answers" : "cases answer"} without one`);
         output.log(`Agent: ${agent.key} @ ${agent.revision}`);
     }
     if (refusal) {
@@ -1432,21 +1452,26 @@ async function checkRun(client, values, pins, selection, agent, output) {
     return 0;
 }
 /**
- * Direct cases: one ordinary experiment through `runExperiment`. The agent receives the case's
- * pinned files and returns generated documents; code evaluators pinned to the run stay deferred
- * for Hue's executor (`deferUnboundLocalScorers`), so no evaluator source runs on this machine.
- * The attempt is checkpointed as in simulation mode: rerunning the same selection resumes the
- * saved experiment without invoking the agent again for its finished cases.
+ * One ordinary experiment through `runExperiment`, for a direct run and for a mixed one. A
+ * direct run's agent receives the case's pinned files and returns generated documents. A mixed
+ * run routes each case by its pin: a case pinning no world goes to the direct adapter, a case
+ * pinning one gets a fresh world through the environment target and the simulation adapter, as
+ * a simulation run gives it. Code evaluators pinned to the run stay deferred for Hue's executor
+ * (`deferUnboundLocalScorers`), so no evaluator source runs on this machine. The attempt is
+ * checkpointed as in simulation mode, under the run kind's own identity: rerunning the same
+ * selection resumes the saved experiment without invoking the agent again for its finished
+ * cases.
  */
-async function runDirect(run, connection) {
-    const { client, values, pins, output, signal } = run;
+async function runExperimentAttempt(run, connection) {
+    const { client, kind, values, pins, output, signal } = run;
     const config = { agentKey: run.agent.key, agentRevision: run.agent.revision };
-    const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], run.agent.key, run.projectId, "direct");
-    const store = await CheckpointStore.acquire(checkpointDirectory, {
-        kind: "direct",
+    const store = await CheckpointStore.acquire(run.checkpointDirectory, {
+        kind,
         projectId: run.projectId,
         baseUrl: connection.baseUrl,
     });
+    // Only a mixed run creates worlds; its world cases reach Hue through the environment client.
+    const environmentClient = kind === "mixed" ? createEnvironmentClient(connection) : undefined;
     let experimentId = "";
     let runUrl = "";
     let report;
@@ -1459,7 +1484,7 @@ async function runDirect(run, connection) {
         });
         let attempt = await store.read("active-attempt");
         if (attempt && attempt.stage !== "completed" && attempt.selectionDigest !== selectionDigest)
-            throw new Error("Recover the unfinished direct run before running a changed selection: run the unchanged command again to finish it, or pass another --checkpoint-dir");
+            throw new Error(`Recover the unfinished ${kind} run before running a changed selection: run the unchanged command again to finish it, or pass another --checkpoint-dir`);
         if (!attempt || attempt.stage === "completed") {
             attempt = { selectionDigest, idempotencyKey: randomUUID(), stage: "preparing" };
             await store.write("active-attempt", attempt);
@@ -1496,10 +1521,41 @@ async function runDirect(run, connection) {
             scorers: [],
             deferUnboundLocalScorers: true,
             environmentEvidence: "when_pinned",
+            // A world case that a process which died here left running runs again in a fresh world;
+            // an answer-only case it left running stays uncertain, since its agent may still be
+            // acting. A direct run gives no case a world, so none of its cases reruns.
+            ...(environmentClient
+                ? { rerunCrashedCases: (item) => Boolean(item.environmentVersionId) }
+                : {}),
             async target(inputs, context) {
                 if (signal.aborted)
                     throw new TargetCancelledError();
-                output.log(`[${context.item.externalKey}] agent started`);
+                const label = context.item.externalKey;
+                if (environmentClient && context.item.environmentVersionId)
+                    return runEnvironmentTarget({
+                        client,
+                        environmentClient,
+                        hue: run.hue,
+                        inputs,
+                        context,
+                        agentRevision: run.agent.revision,
+                        // The CLI adapts to whatever the deployment serves; the library warning is for
+                        // code that still reads the legacy capability itself.
+                        deprecationWarnings: false,
+                        signal,
+                        onProgress(event) {
+                            if (event.type === "world_created")
+                                output.log(`[${label}] world created`);
+                            else if (event.type === "target_started")
+                                output.log(`[${label}] agent started`);
+                            else if (event.type === "world_sealed")
+                                output.log(`[${label}] world sealed`);
+                            else if (event.type === "attempt_prepared")
+                                output.log(`[${label}] attempt prepared: ${event.status}`);
+                        },
+                        target: (targetInputs, targetContext) => run.agents.simulation(structuredClone(targetInputs), simulationTargetContext(targetContext)),
+                    });
+                output.log(`[${label}] agent started`);
                 const result = await run.agents.direct(inputs, {
                     mode: "direct",
                     config: structuredClone(context.config),
@@ -1522,7 +1578,7 @@ async function runDirect(run, connection) {
                 experimentId,
                 subjectIds: report.subjectIds,
                 runUrl,
-                extra: { mode: "direct", deferredScorerVersionIds: report.deferredScorerVersionIds },
+                extra: { mode: kind, deferredScorerVersionIds: report.deferredScorerVersionIds },
                 telemetryNotAccepted: report.telemetryNotAccepted,
             }, { kind: "attempt" });
         attempt.stage = "completed";
@@ -1538,7 +1594,7 @@ async function runDirect(run, connection) {
         experimentId,
         subjectIds: report.subjectIds,
         runUrl,
-        extra: { mode: "direct", deferredScorerVersionIds: report.deferredScorerVersionIds },
+        extra: { mode: kind, deferredScorerVersionIds: report.deferredScorerVersionIds },
         telemetryNotAccepted: report.telemetryNotAccepted,
     }, run.baselineId, output, signal, run.judging);
 }

package/dist/evals/runner.d.ts

@@ -112,8 +112,11 @@ export interface RunExperimentOptions extends RunnerOptions {
     signal?: AbortSignal;
     /** Rerun, as a new attempt, a case that a process which died on this machine left running.
      * Only for targets that give every attempt a fresh world: elsewhere the dead run's agent may
-     * still be acting, so such a case stays uncertain. */
-    rerunCrashedCases?: boolean;
+     * still be acting, so such a case stays uncertain. A predicate decides per frozen case, for a
+     * target that gives a fresh world only to the cases that pin one: those rerun, the others stay
+     * uncertain. The crash is recorded in the case's checkpoint before the case is read, so a read
+     * that fails leaves the decision to the next invocation. */
+    rerunCrashedCases?: boolean | ((item: ExperimentCase) => boolean);
     /** Experiment to run; its dataset version must be frozen. */
     experimentId: string;
     /** Whether each case waits for acknowledged trace export or explicitly omits evidence. Required. */

package/dist/evals/runner.js

@@ -442,6 +442,24 @@ export async function runExperiment(options) {
             .map((version) => version.id),
     };
     try {
+        // A run that reclaimed a dead process's lock first records that a crash sweep is due, then
+        // marks every case that process left running as crashed, before anything else happens and
+        // under the same release as the rest. The record outlives this run: a sweep that stops part
+        // way (a write the disk refuses) is finished by the next run, which holds no reclaimed lock
+        // but reads the record, so each case's recovery decision survives, and a failure further on
+        // (a case read Hue refuses stops the run) leaves it to the next run the same way.
+        const sweep = "crash-sweep";
+        if (store.reclaimed)
+            await store.write(sweep, { pending: true });
+        if ((await store.read(sweep))?.pending) {
+            for (const item of items) {
+                const file = `case-${uuid(item.id)}`;
+                const checkpoint = await store.read(file).catch(() => undefined);
+                if (checkpoint?.stage === "running" && !checkpoint.crashed)
+                    await store.write(file, { ...checkpoint, crashed: true });
+            }
+            await store.write(sweep, { pending: false });
+        }
         const filesRoot = resolve(options.filesDirectory ?? join(options.checkpointDirectory, "files"));
         const sanitize = (message) => message.slice(0, 4000).toWellFormed().replaceAll("\u0000", "");
         // A target stopped at its world's deadline is a `TargetTimeout`, told apart from an error the
@@ -539,10 +557,18 @@ export async function runExperiment(options) {
             files.keepOutputs = checkpoint?.stage === "uploading";
             if (checkpoint && "attempt" in checkpoint)
                 files.directory = worldDirectoryOf(item.id, checkpoint.attempt);
+            // The frozen case, read once per case: the crash decision below and the start need it.
+            let frozen;
+            const frozenCaseOf = async () => (frozen ??= await options.client.getExperimentCase(experiment.id, item.id));
             let retryOf;
-            // A case left running by a process that died here is as interrupted as one the caller
-            // stopped; a fresh world isolates it from anything the dead run's agent still does.
-            if (checkpoint?.stage === "running" && store.reclaimed && options.rerunCrashedCases) {
+            // A case left running by a process that died here (recorded above, before anything was
+            // read) is as interrupted as one the caller stopped; a fresh world isolates it from
+            // anything the dead run's agent still does.
+            if (checkpoint?.stage === "running" &&
+                checkpoint.crashed &&
+                options.rerunCrashedCases &&
+                (typeof options.rerunCrashedCases !== "function" ||
+                    options.rerunCrashedCases(structuredClone(await frozenCaseOf())))) {
                 checkpoint = { ...checkpoint, stage: "interrupted" };
                 await store.write(file, checkpoint);
             }
@@ -572,7 +598,7 @@ export async function runExperiment(options) {
                 // second invocation. Metadata-only mode discarded the output, so its outcome is lost.
                 if (checkpoint.hasOutput && checkpoint.output === undefined)
                     throw new UncertainExecutionError(item.id, checkpoint.executionId);
-                const frozenCase = await options.client.getExperimentCase(experiment.id, item.id);
+                const frozenCase = await frozenCaseOf();
                 checkpoint = await prepare(file, checkpoint, frozenCase, caseDirectoryOf(frozenCase), checkpoint.output);
                 files.keepOutputs = false;
             }
@@ -581,7 +607,7 @@ export async function runExperiment(options) {
                     throw new TargetCancelledError();
                 if (item.execution && item.execution.id !== retryOf)
                     throw new UncertainExecutionError(item.id, item.execution.id);
-                const frozenCase = await options.client.getExperimentCase(experiment.id, item.id);
+                const frozenCase = await frozenCaseOf();
                 if (frozenCase.datasetVersionId !== version.id)
                     throw new Error("Case is not from the pinned dataset version");
                 // Validate before creating a remote execution. SDK/input failures are not

package/dist/evals/simulation.d.ts

@@ -4,6 +4,7 @@ import type { EnvironmentTool } from "../world/tools.js";
 import type { EnvironmentIdentity, PublishableEnvironmentDefinition, WorldHandoff } from "../world/types.js";
 import { type EvaluationClient } from "./client.js";
 import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
+import { type EnvironmentTargetContext } from "./environment-target.js";
 import { type RunnerReport, type TelemetryNotAccepted } from "./runner.js";
 import type { ExperimentCase, Identity, JsonValue, LocalFile, LocalScorer, ScorerDefinition, SimulationMcpCapability, TargetResult } from "./types.js";
 /** Repository-authored scorer identity and its public definition or local binding. */
@@ -222,6 +223,9 @@ export interface SimulationReport extends RunnerReport {
  * @deprecated Use {@link SimulationDefinition}.
  */
 export type SimulationScenario = SimulationDefinition;
+/** The candidate-visible context of a world case, cloned from the environment target's: the
+ * frozen case's identity alone, never its expected outcome, metadata or source pins. */
+export declare function simulationTargetContext(context: EnvironmentTargetContext): SimulationTargetContext;
 /** Run an existing agent callback against one fresh hosted world per case. The helper
  * owns immutable resolution, execution linkage, finalization, scoring and resumable uploads.
  */

package/dist/evals/simulation.js

@@ -344,6 +344,29 @@ async function resolveExperiment(options, definition, idempotencyKey) {
     };
 }
 let scenarioDeprecationWarned = false;
+/** The candidate-visible context of a world case, cloned from the environment target's: the
+ * frozen case's identity alone, never its expected outcome, metadata or source pins. */
+export function simulationTargetContext(context) {
+    return {
+        config: structuredClone(context.config),
+        item: { id: context.item.id, externalKey: context.item.externalKey },
+        executionId: context.executionId,
+        environmentRunId: context.environmentRunId,
+        tools: context.tools,
+        ...(context.world ? { world: structuredClone(context.world) } : {}),
+        ...(context.mcp
+            ? {
+                mcp: { url: context.mcp.url, token: context.mcp.token, expiresAt: context.mcp.expiresAt },
+            }
+            : {}),
+        ...(context.connectionBundle
+            ? { connectionBundle: structuredClone(context.connectionBundle) }
+            : {}),
+        files: structuredClone(context.files),
+        outputDirectory: context.outputDirectory,
+        signal: context.signal,
+    };
+}
 /** Run an existing agent callback against one fresh hosted world per case. The helper
  * owns immutable resolution, execution linkage, finalization, scoring and resumable uploads.
  */
@@ -462,32 +485,7 @@ export async function runSimulation(options) {
                     executionId: context.executionId,
                     caseId: context.item.id,
                 }),
-                target: (targetInputs, targetContext) => options.target(structuredClone(targetInputs), {
-                    config: structuredClone(targetContext.config),
-                    item: {
-                        id: targetContext.item.id,
-                        externalKey: targetContext.item.externalKey,
-                    },
-                    executionId: targetContext.executionId,
-                    environmentRunId: targetContext.environmentRunId,
-                    tools: targetContext.tools,
-                    ...(targetContext.world ? { world: structuredClone(targetContext.world) } : {}),
-                    ...(targetContext.mcp
-                        ? {
-                            mcp: {
-                                url: targetContext.mcp.url,
-                                token: targetContext.mcp.token,
-                                expiresAt: targetContext.mcp.expiresAt,
-                            },
-                        }
-                        : {}),
-                    ...(targetContext.connectionBundle
-                        ? { connectionBundle: structuredClone(targetContext.connectionBundle) }
-                        : {}),
-                    files: structuredClone(targetContext.files),
-                    outputDirectory: targetContext.outputDirectory,
-                    signal: targetContext.signal,
-                }),
+                target: (targetInputs, targetContext) => options.target(structuredClone(targetInputs), simulationTargetContext(targetContext)),
             }),
         });
         const complete = { ...report, experimentId, runUrl };

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.20.2";
+export declare const sdkVersion = "0.20.3";

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.20.2";
+export const sdkVersion = "0.20.3";

package/package.json

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