@hue-run/sdk 0.19.1 → 0.20.0

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.19.1`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.0`, `@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.
 
@@ -379,8 +379,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.19.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.19.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.0 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`
@@ -595,7 +595,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.19.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -606,7 +606,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.19.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -648,10 +648,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.19.1 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.19.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.19.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.19.1 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.20.0 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.20.0 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.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.20.0 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 +689,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.19.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -731,6 +731,23 @@ former; a case failed for its telemetry has `state: "error"`,
 Hue-owned `world_outcome` checks are graded after the world seals. An experiment always covers
 every case of the saved version; there is no case subset.
 
+`--judges` requests the run's pinned
+`llm_judge` evaluators after outputs upload, before verdict polling. It is off by default and
+works in direct, simulation and worker modes. Requests use the project's hosted judge budget;
+Hue applies its admission controls to new jobs. An accepted request remains replayable if the
+budget is later disabled. Cases without stored output are excluded, and combining
+`--judges` with `--no-output` is refused. `--check` creates no judge jobs.
+
+With `--judges --wait 0`, the CLI requests the jobs and returns their current verdict state;
+pending jobs continue in Hue. Uploaded outputs are checkpointed before the attempt or worker
+queue is marked completed. If this handoff or dispatch fails, or its acknowledgement is lost,
+rerun the unchanged command with the same checkpoint directory. The CLI resumes judging the uploaded
+outputs without invoking the agent, using the same idempotency keys. After dispatch succeeds,
+the next ordinary invocation starts a new run as usual.
+
+`--worker --judges` discards cancelled or released handoffs. Once judge requests succeed, a
+verdict-read failure is logged and the worker keeps accepting runs.
+
 `--command "<shell command>"` spawns the command once per case with the world's environment
 (`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `HUE_WORLD_NOW` (the world's clock at creation, RFC 3339; `worldNow()` reads it and returns
 `null` without it, so fall back explicitly with `worldNow() ?? new Date()`), one `HUE_SIM_<SURFACE ID>_URL` per provider

package/ENVIRONMENTS.md

@@ -1,6 +1,6 @@
-# Simulated environments
+# Simulated worlds: compatible client
 
-The provider-aware environment APIs shipped in TypeScript `0.3.0` and are publicly available:
+The provider-aware APIs shipped in TypeScript `0.3.0` and are publicly available:
 
 ```bash
 npm install @hue-run/sdk zod
@@ -10,6 +10,9 @@ Your agent runs in your process while a disposable simulated world runs in Hue.
 authoritative and records an ordered journal; Hue does not execute your agent code or provider
 credentials.
 
+The `environment` module and its exported names remain supported for existing integrations.
+The canonical client names for the next release are documented in [Worlds](WORLDS.md).
+
 ## Run a definition like a test
 
 `runSimulation` is the one-shot developer path. It calls your existing callback directly, so

package/EVALUATIONS.md

@@ -104,6 +104,11 @@ resolution, a fresh linked world per case, local and hosted MCP tools, finalizat
 evidence and scoring while retaining this runner's checkpoint guarantees. See
 [Simulated environments](ENVIRONMENTS.md#run-a-definition-like-a-test).
 
+The `onUploaded` callback in `runSimulation` and `runLocalAgent` supports durable
+application handoffs after outputs upload and before the attempt or worker queue is marked
+completed. A callback failure stops completion and preserves the uploaded work for recovery.
+The callback may run again after an interruption, so make its writes idempotent.
+
 Cases whose inputs are a task plus pinned documents, and rescoring over documents a run already
 saved, use the same runner without a world. See [Direct cases and files](#direct-cases-and-files).
 
@@ -179,7 +184,7 @@ Scorer deferral shipped in TypeScript `0.3.1`: the local runner executes only th
 
 `world_outcome` pins (`hue.conversion_outcome.v1` and `.v2`, and the `hue.outcome_assertions.v2` and `.v3` case-outcome evaluators, `.v3` with its pinned judge in `config.judge`) run inside Hue and need no local callback or executable source digest. A supporting server owns their execution from saved world evidence. Legacy `local_code` pins still require the exact registered callback; changing the worker cannot convert those immutable pins into hosted ones.
 
-Manual results require a human session. Hosted model-judge dispatch is an explicit separate API operation: inspect `getJudgeBudget()`, then call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
+Manual results require a human session. Hosted model-judge dispatch is explicit: call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. Hue checks the project's budget when admitting new requests. `getJudgeBudget()` reports its current state, but replay an interrupted request with the same key and body even if that state changed. The [`hue eval --judges`](./CLI.md#evaluate-an-agent-against-a-case) option performs this dispatch after outputs upload; it is off by default. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
 
 When present, the budget's `authentication` reports credential resolution only. An
 `available` status or `configured: true` does not prove that a provider accepted the

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.19.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.19.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.0 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/WORLDS.md

@@ -0,0 +1,122 @@
+# Simulated worlds
+
+The World clients require a Hue deployment that serves the canonical World and instance routes.
+The [compatible environment client](ENVIRONMENTS.md) remains supported.
+
+Your agent runs locally against an isolated hosted instance of a simulated world:
+
+```bash
+npm install @hue-run/sdk zod
+```
+
+Your agent runs in your process while a disposable simulated world runs in Hue. The world is
+authoritative and records an ordered journal; Hue does not execute your agent code or provider
+credentials.
+
+A World is a reconstructed starting state. An instance is an isolated running copy of that
+state. Starting another instance does not share the first instance's changes. The handoff's
+legacy `worldId` field identifies the runtime instance, not a durable World model.
+
+## Reconstruct a user's World
+
+The World model client requires the corresponding service routes. An entity's
+namespace and full ID bind its history to the project identified by the service key.
+
+```ts
+import { WorldModelClient } from "@hue-run/sdk/world";
+
+const models = new WorldModelClient({ apiKey: process.env.HUE_API_KEY! });
+const { worldModel } = await models.createModel({
+  entity: { namespace: "user", id: "user-123" },
+});
+const { world, instance } = await models.startInstance(worldModel.id, {
+  idempotencyKey: "review-user-123-at-t2",
+  at: "2026-10-17T12:00:00Z",
+  ttlSeconds: 600,
+});
+```
+
+`world.at` is the represented time. `world.evidenceCutoff` names the committed evidence used to
+reconstruct it, including qualifying evidence from traces recorded later. A subsequent start
+with a new idempotency key uses the latest completed reconstruction. Retrying the same key
+replays the original start. `instance.id` identifies the isolated running copy.
+
+`materialize(modelId, { at })` reconstructs without starting an instance.
+`reproduceInstance(instance.id, { idempotencyKey })` starts a fresh isolated instance from the
+original starting World. It does not copy the earlier instance's mutations or reuse its token.
+Erased or unavailable starting data fails explicitly. `eraseModel(modelId)` revokes the model
+and prevents its starting Worlds from being reproduced.
+
+Materialization, instance creation and reproduction wait up to two minutes when Hue explicitly
+reports that the World is preparing. Retries preserve the same request bytes and identity.
+Other failures keep the client's `maxAttempts` limit. Pass `{ signal }` as the last options
+argument to cancel a preparation wait or an active request.
+
+`listModels` and `listAccounts` accept `after` and `limit` for pagination. Use each account's
+`providerInstanceKey` to distinguish connections, including several accounts for one app.
+
+## Capture user and account identity
+
+Automatic World capture requires a compatible service.
+Your existing tracing remains valid without these attributes; unresolved identity does not become
+World state.
+
+Record the complete user ID on the request's root span with `userId`. For another entity kind,
+set both `hue.world.entity.namespace` and `hue.world.entity.id` on that root. Tool observations
+need an explicit connection binding on the actual tool span:
+
+| Attribute | Value |
+| --- | --- |
+| `hue.connection.provider_id` | Registered app ID, such as `google.gmail`. |
+| `hue.connection.account_id` | Your stable account or connection ID, scoped to this user and project. |
+| `hue.connection.generation` | Positive integer identifying that connection generation. Increment when the connection is replaced. |
+| `hue.connection.scope` | Optional app partition, such as a workspace. Keep it stable. |
+| `hue.connection.principal` | The app's acting identity when its simulation requires one. |
+
+For example, attach the binding inside an existing tool callback. `searchThreads` below is your
+application's tool implementation:
+
+```ts
+import { trace } from "@opentelemetry/api";
+import { createHue } from "@hue-run/sdk";
+
+const hue = createHue({
+  serviceName: "assistant",
+  apiKey: process.env.HUE_API_KEY!,
+  resourceAttributes: { "deployment.environment.name": "production" },
+});
+
+await hue.withSpan("assistant request", () =>
+  hue.tool("search_threads", { query: "project update" }, async () => {
+    trace.getSpan(hue.getContext())?.setAttributes({
+      "hue.connection.provider_id": "google.gmail",
+      "hue.connection.account_id": "connection-work",
+      "hue.connection.generation": 1,
+      "hue.connection.principal": "owner@example.test",
+    });
+    return searchThreads({ query: "project update" });
+  }, { mcp: { name: "gmail", provider: "google.gmail", surface: "mcp" } }),
+  { userId: "user-123" },
+);
+await hue.shutdownSafe();
+```
+
+An attached client uses your application's existing OpenTelemetry resource; configure production
+provenance there. Mark faithful production traffic accurately. Eval, simulation and excluded
+traffic cannot populate a live user's World. Historical imports require separate trusted admission.
+
+Use the same fields with your framework's tool-span hook. A parent-only account label cannot
+resolve several accounts used by different tool calls. Account IDs and resource IDs stay separate;
+a tool argument or matching email address alone does not establish a binding. Do not record
+OAuth tokens or provider credentials in these fields.
+
+## Publish an authored World
+
+`createWorldClient` also publishes authored definitions and starts instances from their
+immutable versions. Use `WorldDefinitionV2` and `WorldProviderInstance` for arbitrary registered
+apps and multiple accounts of the same app. The deployment validates each app's JSON
+configuration and supported dialects.
+
+The [compatible client guide](ENVIRONMENTS.md) covers authored definitions, action catalogs,
+instance journals and simulation runners. Its examples use the retained environment client;
+the canonical client uses the same request bodies through World and instance routes.

package/dist/cli/eval.d.ts

@@ -1,3 +1,4 @@
+import { EvaluationClient } from "../evals/client.js";
 import type { ExperimentCase, LocalFile } from "../evals/types.js";
 import { TargetResult } from "../evals/types.js";
 import { type SimulationTargetContext } from "../evals/simulation.js";
@@ -51,6 +52,9 @@ export declare function spawnAgentCommand(command: string, options: {
 }): Promise<string>;
 export declare function renderTable(verdicts: ExperimentVerdicts, output: Output): void;
 export declare function explain(error: unknown): string;
+/** Requests only the run's pinned model judges. Stable batches let an interrupted CLI resume
+ * dispatch without creating a second paid job for the same scoring item and evaluator. */
+export declare function dispatchPinnedJudges(client: Pick<EvaluationClient, "getExperiment" | "listEvaluationItems" | "createJudgeJobs">, experimentId: string, subjectIds: string[], signal?: AbortSignal): Promise<number>;
 /**
  * `hue eval`: runs a local adapter or command against a Scenario or eval set through
  * `runSimulation`, or registers it as an outbound worker through `runLocalAgent`.