@hue-run/sdk 0.20.1 → 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.1`, `@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.
 
@@ -115,6 +115,8 @@ hue login                 # validate keys created in Hue and store them in ./.en
 hue mcp install --client claude-code # write the Hue MCP configuration for a coding agent
 hue listen --subscription <id> --forward-to http://localhost:3000/slack/events # deliver events to a local bot
 hue import langfuse --from 2026-01-01 --dry-run # count a Langfuse project's traces, then import them
+hue traces import prepare ./exports --out ./exports.hue-import --json # convert exports into a bundle
+hue traces import upload ./exports.hue-import --authorization-file ./authorization.json --json # deliver it
 ```
 
 Hosted setup accepts HTTPS origins only. HTTP is accepted solely for `localhost`, `127.0.0.1` and
@@ -379,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.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.1 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`
@@ -491,6 +493,96 @@ once, abandoning exports still in flight for the next run to send. Exit codes: `
 trace was imported, `1` a trace, span or file was not (or a key was refused), `2` usage error, `130`
 stopped.
 
+## Import a bundle of existing traces
+
+`hue traces import` brings historical traces into Hue from exports you already hold: OTLP/JSON
+trace exports (a `{"resourceSpans": […]}` document, a list of them, or one per line), complete
+Langfuse observation exports (the `data` or native `observations` envelope) and text ATIF v1.7 and
+v1.8 exports, embedded subagents included. It needs no project key. `prepare` runs on the machine
+that holds the exports and sends nothing; a Hue MCP connection then authorizes the delivery
+(`prepare_trace_import`); `upload` delivers the bundle with that authorization, and
+`get_trace_import` reports what arrived.
+
+```sh
+npx -y @hue-run/sdk@latest traces import prepare ./exports --out ./exports.hue-import --json
+npx -y @hue-run/sdk@latest traces import upload ./exports.hue-import --authorization-file ./authorization.json --json
+```
+
+**Prepare.** `prepare <path>` reads a file, a directory tree or a ZIP archive (members are inflated
+in memory; encrypted members, unsafe paths and nested archives are listed, not read) and
+recognizes each file by its content, never by its name. Every trace becomes gzip OTLP/JSON batches
+of at most 3 MiB decoded and 900 KiB on the wire, written to `--out` (default `<path>.hue-import`,
+created with mode 0700) beside `manifest.json`, which declares each trace's id, span count, batches
+(by the SHA-256 of each gzip body), large values, history owner and origin. A text value over 1 MiB
+is stored as a value of its own and listed in `hue.blobs`, as the exporter lists the values it
+uploads. OTLP spans are kept as recorded; a trace or span id that is not an OpenTelemetry id (an
+exporter's UUID, for example) is mapped to one derived from it by SHA-256, with the original kept
+as `hue.import.original_trace_id` or `hue.import.original_span_id`. A Langfuse observation becomes
+one span keeping its whole record (`hue.import.source_record`) beside the `langfuse.*` and GenAI
+attributes Hue reads; an id that is no OpenTelemetry id is mapped as `hue import langfuse` maps it,
+so an export and a live import of the same trace agree. An ATIF export becomes one trace: an agent
+span for the run, a model span per agent step with the conversation so far, a tool span per call,
+each embedded subagent as its own agent span under the call that spawned it, and the export's
+`extra.user_id` as the trace's `user.id`. ATIF records instants, not durations, so model and tool
+spans are points in time, and a tool's result is kept as text with no error status of the
+importer's making. The same trace in two files is one trace when the copies agree and a refusal
+when they differ; a trace with more than 100,000 spans, 64 batches or 1,000 values is refused and
+named. Nothing about where a file sat or what it was called reaches a span: a renamed, reordered
+or re-zipped copy of the bundle prepares to byte-identical batches and the same manifest digest.
+
+The report (`--json` prints it as one object) names `manifest_digest`, `totals` (traces, batches,
+spans, blobs, bytes) and `source`, which `prepare_trace_import` takes as given; the formats
+recognized and the traces each file held; the files it could not read, with the reason; the traces
+and spans it refused; the traces without a history owner (a root `user.id`, a Langfuse `userId`, an
+ATIF `extra.user_id`, or an explicit `hue.world.entity.namespace` and `hue.world.entity.id`), which
+import like any other trace but leave a gap in continuous history; the origin each source recorded
+(`production`, `evaluation`, `simulation` or `unknown`; evaluation and simulation traffic is
+imported and kept out of production history); and the traces whose vendor ids were mapped. An
+existing `--out` directory is accepted only while it holds nothing but an earlier preparation and
+no upload has started in it.
+
+**Authorize.** Call `prepare_trace_import` over the Hue MCP with the report's `manifest_digest`,
+`totals` and `source`. It answers the import id, `upload_url` and an `authorization` (`hue_it_` and
+43 characters) valid for an hour. Save its answer, or the authorization alone, in a private file
+(mode 0600; never in a transcript, a message or a shell history). The same digest in the same
+project is the same import: calling again renews the authorization for an interrupted upload and
+revokes the earlier one.
+
+**Upload.** `upload <directory> --authorization-file <file>` reads the authorization from the file
+(its JSON answer, or the authorization on the first line and the `upload_url` on the second;
+`--import-url` names the URL otherwise, and `--origin` refuses a URL on any other Hue origin),
+never from the command line or the environment, and never prints it. It registers the manifest's
+exact bytes, then, trace by trace in declared order and two requests at a time, reserves each large
+value, sends it to the URL Hue answers and completes it, posts each batch with its SHA-256 in
+`Hue-Import-Batch`, and reads the trace's receipt for every span id: a trace counts as verified only
+when Hue confirms every span. It then reconciles and completes the import. Progress is written to
+`progress.json` in the bundle as it goes; running the same command again resumes there, and what
+Hue already holds is not sent twice (a batch sent again after a lost acknowledgement is taken as
+duplicates). Connection failures, timeouts, `408`, `429` and `5xx` answers are retried after 1, 2,
+4, 8, 16 and 30 seconds, waiting for `Retry-After`; after eight retries the command stops and the
+next run resumes. Ctrl+C or `SIGTERM` finishes the requests in flight, saves progress and exits
+`130`; a second signal stops at once.
+
+**What Hue refuses.** Every refusal carries a fixed code, which the report names in `error.code`.
+An expired or replaced authorization (`401`), a lapsed connection (`403` `authority_lapsed`) and an
+expired import (`410`) stop the upload: call `prepare_trace_import` again with the same
+`manifest_digest` and `totals`, write the new authorization to the file and run the same command.
+A manifest whose digest or totals are not the import's (`409`), an authorization of another import
+(`403`), an unknown import (`404`) and a canceled import (`410`) are final. A batch or value Hue
+refuses for the trace's own sake (undeclared, another digest, another trace's records, fewer
+finished spans than declared, a size or type the manifest did not declare), or a record Hue already
+holds under the same id with other content, is a conflict: it is recorded, the trace is reported,
+none of its later records are sent, and the same bytes are never sent again. An import Hue reports
+already completed is done: the command exits `0` and points to `get_trace_import`.
+
+**Output and exit codes.** Without `--json`, the command prints the registration, every hundredth
+verified trace, each conflict and a summary. With `--json`, one progress object per line goes to
+stderr and the report to stdout: the state (`completed`, `incomplete`, `stopped` or `failed`), the
+traces verified and conflicted, the batches landed and values stored, Hue's own note and the traces
+it still lists when completion was refused, the conflicts with their codes, and `next_action`. Exit
+codes: `0` prepared or completed, `1` not completed (the report says what to do next), `2` usage
+error, `130` stopped.
+
 ## Local state and conflicts
 
 Before its first network write, setup creates a lowercase UUIDv4 and a 32-byte random installation
@@ -595,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.1.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
@@ -606,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.1.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
@@ -648,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.1 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.1 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.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.1 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
@@ -689,7 +781,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.1 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/ENVIRONMENTS.md

@@ -332,7 +332,7 @@ A refusal such as 409 `simulation_gateway_required` exposes its validated server
 
 `agentEnvironment` removes Hue control-plane credentials from the child by default: `HUE_API_KEY`,
 `HUE_MCP_KEY`, and any value carrying a Hue control-plane credential (`hue_sk_`, `hue_setup_`,
-`hue_attempt_`, `hue_mcp_`, `hue_inv_`, `hue_install_`, `hue_at_`, `hue_rt_`, `hue_oauth_`)
+`hue_attempt_`, `hue_mcp_`, `hue_inv_`, `hue_install_`, `hue_at_`, `hue_rt_`, `hue_it_`, `hue_oauth_`)
 anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. World tokens and
 `hue_sim_` capabilities pass. Pass `includeHueCredentials: true` only for an agent that must call
 Hue's own API.

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.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.1 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
@@ -558,6 +558,34 @@ The command has no Python counterpart; it runs with `npx` for an application in
 [Import traces from Langfuse](CLI.md#import-traces-from-langfuse) for every option, the attribute
 mapping, media handling, limits and exit codes.
 
+## Import a bundle of existing traces
+
+`hue traces import` brings exports you already hold into Hue in two steps, with no project key.
+`prepare` converts the bundle on your machine and sends nothing; a Hue MCP connection authorizes
+the delivery with `prepare_trace_import`; `upload` delivers it with that authorization. Sources
+are files, directories or ZIP archives of OTLP/JSON trace exports, complete Langfuse observation
+exports and text ATIF v1.7 and v1.8 exports, recognized by content:
+
+```sh
+npx -y @hue-run/sdk@latest traces import prepare ./exports --out ./exports.hue-import --json
+# Call prepare_trace_import with the report's manifest_digest, totals and source, and save its
+# answer (or the authorization alone) in a private file.
+npx -y @hue-run/sdk@latest traces import upload ./exports.hue-import --authorization-file ./authorization.json --json
+```
+
+- `prepare` writes each trace as gzip OTLP/JSON batches beside a manifest and reports the
+  manifest's digest and totals, the formats recognized, the files it could not read, invalid vendor
+  ids it mapped to OpenTelemetry ids, and the traces without a history owner (a root `user.id` or an
+  explicit entity). Nothing about a file's name or place reaches a span.
+- `upload` registers the manifest, sends each trace's large values and batches in order, two
+  requests at a time, checks every span's receipt, reconciles and completes the import. Interrupted,
+  run it again: it resumes from `progress.json` in the bundle. An expired authorization is renewed
+  by calling `prepare_trace_import` again with the same digest and totals.
+- The authorization (`hue_it_…`) is read only from the file and never printed.
+
+See [Import a bundle of existing traces](CLI.md#import-a-bundle-of-existing-traces) for the
+formats, the report, what Hue refuses and the exit codes.
+
 ## Vercel AI SDK 6
 
 AI SDK 6 accepts a per-call tracer through `experimental_telemetry`. Pass

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);
 }