@hue-run/sdk 0.19.1 → 0.20.0

package/dist/environment/world.d.ts

@@ -1,65 +1,2 @@
-import type { EnvironmentRun, LegacyMcpCapability, WorldHandoff } from "./types.js";
-/**
- * The world an agent acts on through provider mirrors, read from a create or replay response.
- * Null for a world created while the gateway was off: that world has Hue-native tools and no
- * mirror URLs. The handoff carries the world token; keep it out of logs and checkpoints.
- */
-export declare function worldHandoff(run: EnvironmentRun): WorldHandoff | null;
-/**
- * The world's clock: what an agent reads for today's date in place of the wall clock, so a
- * date-relative request (tomorrow, `newer_than:7d`, this month) lands on the dates the world
- * holds however long after the recording the run starts. From the handoff's `now`, else from
- * `HUE_WORLD_NOW` in the given environment (this process's by default, where `hue eval
- * --command` and `agentEnvironment` set it). Null when neither names it.
- */
-export declare function worldNow(source?: WorldHandoff | Record<string, string | undefined>): Date | null;
-/** Variables that authenticate against Hue's control plane rather than a simulated provider. */
-export declare const HUE_CONTROL_PLANE_VARIABLES: readonly string[];
-/** Prefixes of the Hue control-plane credentials the server issues: project and setup keys,
- * attempt grants, the project MCP key, invocation and installation tokens, and OAuth tokens and
- * secrets. World tokens (`hue_world_`) and MCP capabilities (`hue_sim_`) are what the agent holds. */
-export declare const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES: readonly string[];
-/** True for a control-plane variable by name, or for a value carrying a Hue control-plane
- * credential anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. */
-export declare function isHueControlPlaneCredential(name: string, value: string | undefined): boolean;
-/** The parent's variables without Hue control-plane credentials; `undefined` values are dropped. */
-export declare function stripHueControlPlaneCredentials(parent: Record<string, string | undefined>): Record<string, string>;
-/** Options for {@link agentEnvironment}. */
-export interface AgentEnvironmentOptions {
-    /** The environment to start from; defaults to this process's. */
-    parent?: Record<string, string | undefined>;
-    /** Keep Hue control-plane credentials in the child. Off by default: the agent gets world
-     * tokens only (plan section 10.3) and the project key stays with the runner. */
-    includeHueCredentials?: boolean;
-    /** Also set `HUE_MCP_URL`, `HUE_MCP_TOKEN` and `HUE_MCP_EXPIRES_AT` from the world's first
-     * MCP mirror, the names the `hue_sim_` bridge used, for one compatibility release. On by
-     * 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 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
- * world's first MCP mirror so an adapter written for the bridge keeps working through the
- * compatibility release. Undefined for a world without an MCP surface. */
-export declare function legacyMcpCapability(world: WorldHandoff): LegacyMcpCapability | undefined;
-/** The owner-only `mcpServers` file {@link writeMcpConfig} wrote. */
-export interface McpConfigFile {
-    /** The owner-only file; pass its path to the harness and dispose after the run. */
-    path: string;
-    /** Removes the file and its private directory; safe to call twice. */
-    dispose(): Promise<void>;
-}
-/**
- * Writes the world's `mcpConfig` as an owner-only file in a private directory (plan section
- * 4.9): the file carries the world token, so it is created with mode 0600 inside a 0700
- * directory, is never logged, and `dispose` removes the directory after the run.
- */
-export declare function writeMcpConfig(world: WorldHandoff, options?: {
-    directory?: string;
-}): Promise<McpConfigFile>;
+/** Compatibility entry point. Use the world module. */
+export * from "../world/world.js";

package/dist/environment/world.js

@@ -1,171 +1,2 @@
-import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-/**
- * The world an agent acts on through provider mirrors, read from a create or replay response.
- * Null for a world created while the gateway was off: that world has Hue-native tools and no
- * mirror URLs. The handoff carries the world token; keep it out of logs and checkpoints.
- */
-export function worldHandoff(run) {
-    if (!run.token || !run.env || !run.mcpConfig || !run.surfaces)
-        return null;
-    const id = run.worldId ?? run.id;
-    return {
-        id,
-        token: run.token,
-        expiresAt: run.expiresAt,
-        lifecycle: run.lifecycle ?? "live",
-        completingUntil: run.completingUntil ?? null,
-        traceparent: run.traceparent ?? null,
-        baggage: run.baggage ?? `hue-world=${id}`,
-        now: run.now ?? run.env.HUE_WORLD_NOW ?? null,
-        surfaces: run.surfaces.map((surface) => ({ ...surface })),
-        env: { ...run.env },
-        mcpConfig: {
-            mcpServers: Object.fromEntries(Object.entries(run.mcpConfig.mcpServers).map(([name, server]) => [
-                name,
-                { type: server.type, url: server.url, headers: { ...server.headers } },
-            ])),
-        },
-    };
-}
-/**
- * The world's clock: what an agent reads for today's date in place of the wall clock, so a
- * date-relative request (tomorrow, `newer_than:7d`, this month) lands on the dates the world
- * holds however long after the recording the run starts. From the handoff's `now`, else from
- * `HUE_WORLD_NOW` in the given environment (this process's by default, where `hue eval
- * --command` and `agentEnvironment` set it). Null when neither names it.
- */
-export function worldNow(source = process.env) {
-    const text = "env" in source && typeof source.env === "object" && source.env !== null
-        ? (source.now ?? source.env.HUE_WORLD_NOW)
-        : source.HUE_WORLD_NOW;
-    if (!text)
-        return null;
-    const date = new Date(text);
-    return Number.isNaN(date.getTime()) ? null : date;
-}
-/** Variables that authenticate against Hue's control plane rather than a simulated provider. */
-export const HUE_CONTROL_PLANE_VARIABLES = [
-    "HUE_API_KEY",
-    "HUE_MCP_KEY",
-    "HUE_PROJECT_KEY",
-    "HUE_SERVICE_KEY",
-];
-/** Prefixes of the Hue control-plane credentials the server issues: project and setup keys,
- * attempt grants, the project MCP key, invocation and installation tokens, and OAuth tokens and
- * secrets. World tokens (`hue_world_`) and MCP capabilities (`hue_sim_`) are what the agent holds. */
-export const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES = [
-    "hue_sk_",
-    "hue_attempt_",
-    "hue_mcp_",
-    "hue_setup_",
-    "hue_inv_",
-    "hue_install_",
-    "hue_at_",
-    "hue_rt_",
-    "hue_oauth_",
-];
-/** A Hue credential anywhere in a value, including JSON Unicode escapes, not inside a longer word. */
-const HUE_CREDENTIAL_SHAPE = new RegExp(`(?:^|[^A-Za-z0-9_])(?:${HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES.join("|")})`);
-const ASCII_PERCENT_ESCAPE = /%[0-7][0-9a-f]/i;
-const ASCII_JSON_UNICODE_ESCAPE = /\\u00([0-7][0-9a-fA-F])/g;
-function decodeAsciiJsonUnicodeEscapes(value) {
-    return value.replace(ASCII_JSON_UNICODE_ESCAPE, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
-}
-function hasHueControlPlaneCredential(value) {
-    let candidates = new Set([value]);
-    for (let layer = 0; layer <= 4; layer++) {
-        const jsonDecodedCandidates = new Set();
-        for (const candidate of candidates) {
-            jsonDecodedCandidates.add(candidate);
-            jsonDecodedCandidates.add(decodeAsciiJsonUnicodeEscapes(candidate));
-        }
-        if ([...jsonDecodedCandidates].some((candidate) => HUE_CREDENTIAL_SHAPE.test(candidate)))
-            return true;
-        if (layer === 4)
-            return [...jsonDecodedCandidates].some((candidate) => ASCII_PERCENT_ESCAPE.test(candidate));
-        candidates = new Set([...jsonDecodedCandidates]
-            .filter((candidate) => ASCII_PERCENT_ESCAPE.test(candidate))
-            .map((candidate) => candidate.replace(/%([0-7][0-9a-f])/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))));
-        if (candidates.size === 0)
-            return false;
-    }
-    return false;
-}
-/** True for a control-plane variable by name, or for a value carrying a Hue control-plane
- * credential anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. */
-export function isHueControlPlaneCredential(name, value) {
-    if (HUE_CONTROL_PLANE_VARIABLES.includes(name))
-        return true;
-    return typeof value === "string" && hasHueControlPlaneCredential(value);
-}
-/** The parent's variables without Hue control-plane credentials; `undefined` values are dropped. */
-export function stripHueControlPlaneCredentials(parent) {
-    const child = {};
-    for (const [name, value] of Object.entries(parent)) {
-        if (value === undefined || isHueControlPlaneCredential(name, value))
-            continue;
-        child[name] = value;
-    }
-    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 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 = withoutWorldVariables(options.includeHueCredentials
-        ? Object.fromEntries(Object.entries(parent).filter((entry) => entry[1] !== undefined))
-        : stripHueControlPlaneCredentials(parent));
-    Object.assign(child, world.env);
-    if (options.legacyMcpVariables ?? true) {
-        const legacy = legacyMcpCapability(world);
-        if (legacy) {
-            child.HUE_MCP_URL = legacy.url;
-            child.HUE_MCP_TOKEN = legacy.token;
-            child.HUE_MCP_EXPIRES_AT = legacy.expiresAt;
-        }
-    }
-    return child;
-}
-/** The `{ url, token, expiresAt }` shape the `hue_sim_` capability had, projected from the
- * world's first MCP mirror so an adapter written for the bridge keeps working through the
- * compatibility release. Undefined for a world without an MCP surface. */
-export function legacyMcpCapability(world) {
-    const server = Object.values(world.mcpConfig.mcpServers)[0];
-    if (!server)
-        return undefined;
-    return { url: server.url, token: world.token, expiresAt: world.expiresAt };
-}
-/**
- * Writes the world's `mcpConfig` as an owner-only file in a private directory (plan section
- * 4.9): the file carries the world token, so it is created with mode 0600 inside a 0700
- * directory, is never logged, and `dispose` removes the directory after the run.
- */
-export async function writeMcpConfig(world, options = {}) {
-    const directory = await mkdtemp(join(options.directory ?? tmpdir(), "hue-world-"));
-    const dispose = () => rm(directory, { recursive: true, force: true });
-    try {
-        await chmod(directory, 0o700);
-        const path = join(directory, "mcp.json");
-        await writeFile(path, `${JSON.stringify(world.mcpConfig, null, 2)}\n`, { mode: 0o600 });
-        return { path, dispose };
-    }
-    catch (error) {
-        // A half-written file would hold the token; never leave it behind.
-        await dispose();
-        throw error;
-    }
-}
+/** Compatibility entry point. Use the world module. */
+export * from "../world/world.js";

package/dist/environment.d.ts

@@ -1,7 +1,7 @@
-export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./environment/client.js";
-export type { EnvironmentClientOptions } from "./environment/client.js";
-export { bindEnvironmentTools } from "./environment/tools.js";
-export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./environment/tools.js";
-export type * from "./environment/types.js";
-export { agentEnvironment, HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";
-export type { AgentEnvironmentOptions, McpConfigFile } from "./environment/world.js";
+export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./world/client.js";
+export type { EnvironmentClientOptions } from "./world/client.js";
+export { bindEnvironmentTools } from "./world/tools.js";
+export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./world/tools.js";
+export type * from "./world/types.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./world/world.js";
+export type { AgentEnvironmentOptions, McpConfigFile } from "./world/world.js";

package/dist/environment.js

@@ -1,3 +1,3 @@
-export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./environment/client.js";
-export { bindEnvironmentTools } from "./environment/tools.js";
-export { agentEnvironment, HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./environment/world.js";
+export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, isTransientEnvironmentError, } from "./world/client.js";
+export { bindEnvironmentTools } from "./world/tools.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, worldNow, writeMcpConfig, } from "./world/world.js";

package/dist/evals/attempt.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod/v4";
-import type { CoverageGap } from "../environment/types.js";
+import type { CoverageGap } from "../world/types.js";
 import type { SimulationMcpCapability } from "./types.js";
 /** Canonical caller-observed agent configuration after missing evidence is made explicit. */
 export type ActualAgentManifestV2 = {

package/dist/evals/client.d.ts

@@ -216,7 +216,7 @@ export declare class EvaluationClient {
     getEnvironmentSteps(executionId: string, page?: {
         after?: number;
         limit?: number;
-    }): Promise<import("../environment/types.js").StepPage>;
+    }): Promise<import("../world/types.js").StepPage>;
     /**
      * Prepares the immutable provider-profile binding for one execution. The route identity is
      * removed from the JSON body, and credential-bearing responses are validated against the
@@ -367,7 +367,8 @@ export declare class EvaluationClient {
     listScoringResults(id: string, page?: PageOptions): Promise<Page<ScoringResultSummary>>;
     /** Reads a stored evaluator result. */
     getScoringResult(id: string): Promise<StoredScoringResult>;
-    /** Dispatches hosted judge jobs for `llm_judge` pins; check {@link getJudgeBudget} first. */
+    /** Dispatches hosted judge jobs for `llm_judge` pins. Hue checks admission for new requests;
+     * replay an interrupted request with its original key and body even if the budget changed. */
     createJudgeJobs(id: string, input: {
         idempotencyKey: string;
         jobs: {

package/dist/evals/client.js

@@ -837,7 +837,8 @@ export class EvaluationClient {
     async getScoringResult(id) {
         return productRunFields(await this.getResult(id), "result");
     }
-    /** Dispatches hosted judge jobs for `llm_judge` pins; check {@link getJudgeBudget} first. */
+    /** Dispatches hosted judge jobs for `llm_judge` pins. Hue checks admission for new requests;
+     * replay an interrupted request with its original key and body even if the budget changed. */
     createJudgeJobs(id, input) {
         return this.request("POST", `/evaluation-runs/${uuid(id)}/judge-jobs`, input);
     }

package/dist/evals/environment-target.d.ts

@@ -1,7 +1,7 @@
 import type { HueClient } from "../client.js";
-import { type EnvironmentClient } from "../environment/client.js";
-import { type EnvironmentTool } from "../environment/tools.js";
-import type { EnvironmentRun, WorldHandoff } from "../environment/types.js";
+import { type EnvironmentClient } from "../world/client.js";
+import { type EnvironmentTool } from "../world/tools.js";
+import type { EnvironmentRun, WorldHandoff } from "../world/types.js";
 import type { HueSpan } from "../types.js";
 import { type ActualAgentManifestInputV2, type AttemptBaselineV2, type AttemptConnectionBundleV2, type RequestedAttemptProviderV2, type SurfaceBindingV2 } from "./attempt.js";
 import type { EvaluationClient } from "./client.js";

package/dist/evals/environment-target.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { HueEnvironmentError, isTransientEnvironmentError, } from "../environment/client.js";
-import { bindEnvironmentTools } from "../environment/tools.js";
-import { legacyMcpCapability, worldHandoff } from "../environment/world.js";
+import { HueEnvironmentError, isTransientEnvironmentError, } from "../world/client.js";
+import { bindEnvironmentTools } from "../world/tools.js";
+import { legacyMcpCapability, worldHandoff } from "../world/world.js";
 import { actualAgentManifestV2, attemptBaselineV2, projectMcpConnectionV2, requestedAttemptProvidersV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
 import { TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError } from "./runner.js";
 export function requestedAttemptV2(options) {

package/dist/evals/failure.js

@@ -1,5 +1,5 @@
 import { HueConnectionError } from "../client.js";
-import { HueEnvironmentError } from "../environment/client.js";
+import { HueEnvironmentError } from "../world/client.js";
 import { HueApiError } from "./client.js";
 const TIMEOUT_NAMES = new Set(["TimeoutError", "APIConnectionTimeoutError", "APITimeoutError"]);
 /** Node's and Undici's codes for a call that timed out, connecting or waiting on the answer. */

package/dist/evals/local-worker.d.ts

@@ -1,7 +1,7 @@
 import type { HueClient } from "../client.js";
-import { type EnvironmentClient } from "../environment/client.js";
-import type { EnvironmentTool } from "../environment/tools.js";
-import type { WorldHandoff } from "../environment/types.js";
+import { type EnvironmentClient } from "../world/client.js";
+import type { EnvironmentTool } from "../world/tools.js";
+import type { WorldHandoff } from "../world/types.js";
 import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
 import type { EvaluationClient } from "./client.js";
 import { type RunExperimentTargetContext, type RunnerReport, type TelemetryNotAccepted } from "./runner.js";
@@ -161,6 +161,11 @@ export interface RunLocalAgentOptions {
     /** Runs ordinary cases without a world (`direct:v1`): the agent receives the case inputs
      * and verified input files and returns JSON output and/or generated files. */
     directTarget?(inputs: JsonValue, context: LocalAgentDirectContext): JsonValue | TargetResult | undefined | Promise<JsonValue | TargetResult | undefined>;
+    /** Called after outputs upload, before queue completion. A failure stops the worker with
+     * its claim intact. A resumed claim may repeat this callback without invoking the agent. */
+    onUploaded?(report: RunnerReport, claim: LocalAgentClaim & {
+        workerId: string;
+    }): void | Promise<void>;
     /** Called after the experiment and queue completion are acknowledged. */
     onCompleted?(report: RunnerReport): void | Promise<void>;
 }

package/dist/evals/local-worker.js

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { isTransientEnvironmentError } from "../environment/client.js";
+import { isTransientEnvironmentError } from "../world/client.js";
 import { HueApiError, isTransientApiError } from "./client.js";
 import { HueExportError } from "../transport.js";
 import { CheckpointStore, checkpointPath, checkpointSegment } from "./checkpoint.js";
@@ -252,6 +252,7 @@ export async function runLocalAgent(options) {
             }, Math.min(15_000, Math.max(1_000, interval)));
             let experimentFinished = false;
             let queueCompleted = false;
+            let handoffFailed = false;
             try {
                 const requested = requestedConfiguration
                     ? pinRequestedAttemptV2(requestedConfiguration, (await options.client.getExperiment(experimentId)).config)
@@ -307,6 +308,13 @@ export async function runLocalAgent(options) {
                 // queue completion fails, leave the claim intact for checkpointed recovery instead of
                 // rewriting a successful experiment as an agent failure.
                 experimentFinished = true;
+                try {
+                    await options.onUploaded?.(report, { ...claim, workerId });
+                }
+                catch (error) {
+                    handoffFailed = true;
+                    throw error;
+                }
                 await options.client.completeLocalAgentRun({
                     runId: claim.runId,
                     workerId,
@@ -320,7 +328,7 @@ export async function runLocalAgent(options) {
             catch (error) {
                 // The run is completed in the queue: a failure after that is the caller's own
                 // (`onCompleted` threw) and is thrown as itself, not reported as a retry that cannot be.
-                if (queueCompleted)
+                if (queueCompleted || handoffFailed)
                     throw error;
                 if (experimentFinished && error instanceof HueApiError && error.status === 409) {
                     // The experiment finished, but Hue no longer accepts this worker's completion: the

package/dist/evals/simulation.d.ts

@@ -1,7 +1,7 @@
 import type { HueClient } from "../client.js";
-import { type EnvironmentClient } from "../environment/client.js";
-import type { EnvironmentTool } from "../environment/tools.js";
-import type { EnvironmentIdentity, PublishableEnvironmentDefinition, WorldHandoff } from "../environment/types.js";
+import { type EnvironmentClient } from "../world/client.js";
+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 RunnerReport, type TelemetryNotAccepted } from "./runner.js";
@@ -205,6 +205,9 @@ export interface RunSimulationOptions {
     /** Invokes the existing local agent exactly once for this attempt; return the output, or
      * `withFiles(output, files)` when it generated files. */
     target(inputs: JsonValue, context: SimulationTargetContext): JsonValue | TargetResult | undefined | Promise<JsonValue | TargetResult | undefined>;
+    /** Called after outputs upload and before the attempt is marked completed. A failure leaves
+     * the uploaded attempt resumable. The callback may be repeated after an interruption. */
+    onUploaded?(report: SimulationReport): void | Promise<void>;
     /** Receives bounded nonsecret lifecycle progress. */
     onProgress?(event: SimulationProgress): void | Promise<void>;
 }

package/dist/evals/simulation.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { HueEnvironmentError } from "../environment/client.js";
+import { HueEnvironmentError } from "../world/client.js";
 import { HueApiError } from "./client.js";
 import { CheckpointStore, checkpointPath, checkpointSegment } from "./checkpoint.js";
 import { MAX_ENVIRONMENT_STEPS } from "./environment-evidence.js";
@@ -491,6 +491,7 @@ export async function runSimulation(options) {
             }),
         });
         const complete = { ...report, experimentId, runUrl };
+        await options.onUploaded?.(complete);
         attempt.stage = "completed";
         attempt.report = complete;
         await store.write("active-attempt", attempt);

package/dist/evals/types.d.ts

@@ -1,5 +1,5 @@
 import type { JsonValue } from "../types.js";
-import type { EnvironmentCoverage } from "../environment/types.js";
+import type { EnvironmentCoverage } from "../world/types.js";
 export type { JsonValue } from "../types.js";
 /** One page of a paginated list. */
 export interface Page<T> {
@@ -947,7 +947,7 @@ export interface EnvironmentEvidenceSnapshot extends EnvironmentCoverage {
 /** Sealed environment evidence with its full ordered journal. */
 export interface EnvironmentEvidence extends EnvironmentEvidenceSnapshot {
     /** Complete steps ordered by ordinal. */
-    steps: import("../environment/types.js").Step[];
+    steps: import("../world/types.js").Step[];
 }
 /** A local scorer: its pinned definition and the callback bound to it. */
 export interface LocalScorer {

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

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

package/dist/world/client.d.ts

@@ -0,0 +1,150 @@
+import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, PublishableEnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions, WorldEvidence, WorldEvidenceOptions } from "./types.js";
+import type { PublishableWorldDefinition, WorldVersion } from "./definitions.js";
+/** Connection and retry options for {@link createEnvironmentClient}. */
+export interface EnvironmentClientOptions {
+    /** Project service key sent as a bearer token; server-side only. */
+    apiKey: string;
+    /** Hue origin; defaults to `https://app.hue.run`. */
+    baseUrl?: string;
+    /** Per-request deadline in milliseconds. */
+    timeoutMillis?: number;
+    /** Attempts for idempotent run mutations, 1–10; defaults to 4. */
+    maxAttempts?: number;
+}
+/** Sanitized environment API failure that never includes response text or credentials. */
+export declare class HueEnvironmentError extends Error {
+    /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
+    readonly status?: number | undefined;
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    readonly retryAfterMs?: number | undefined;
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    readonly diagnostic?: string | undefined;
+    constructor(
+    /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
+    status?: number | undefined, 
+    /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
+    retryAfterMs?: number | undefined, 
+    /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
+    diagnostic?: string | undefined);
+}
+/** Starts one isolated instance from an immutable World version. */
+export interface CreateInstanceInput extends Omit<CreateRunInput, "environmentVersionId"> {
+    /** Immutable World version to instantiate. */
+    worldVersionId: string;
+}
+/** A connection failure or a status the client retries; seal polling continues through these. */
+export declare function isTransientEnvironmentError(error: unknown): boolean;
+/** Typed client for authored environments, isolated runs and immutable journals. */
+export declare class WorldClient {
+    #private;
+    /** Validated Hue origin. */
+    readonly baseUrl: string;
+    private readonly timeoutMillis;
+    private readonly maxAttempts;
+    constructor(options: EnvironmentClientOptions);
+    /** Compatibility clients override only resource routing. */
+    protected resourcePath(path: string): string;
+    private send;
+    private page;
+    /** Creates an isolated instance from an immutable World version. */
+    createInstance(input: CreateInstanceInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentRun>;
+    /** Reads current or sealed instance state. */
+    getInstance(instanceId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+        environmentVersionId: string;
+        executionId: string | null;
+        seed: string;
+        status: "open" | "completed" | "abandoned" | "expired";
+        stepCount: number;
+        maxSteps: number;
+        clockNs: string;
+        expiresAt: string;
+        createdAt: string;
+        sealedAt: string | null;
+        stateDigest: string;
+        finalState?: import("./types.js").JsonValue;
+        worldId?: string;
+        lifecycle?: import("./types.js").WorldLifecycle;
+        completingUntil?: string | null;
+        traceExternalId?: string | null;
+        surfaces?: import("./types.js").WorldSurface[];
+        flags?: import("./types.js").WorldFlag[];
+        connection?: null;
+        validity: "environment_incomplete" | "not_assessed";
+        coverageGap: import("./types.js").CoverageGap | null;
+    }>;
+    /** Completes or abandons one instance and freezes its evidence. */
+    finishInstance(instanceId: string, input: FinishRunInput): Promise<SealedRun>;
+    /** Creates an environment identity; this non-idempotent registry write is not retried. */
+    createEnvironment(input: EnvironmentIdentity): Promise<EnvironmentSummary>;
+    /** Lists active environment identities. */
+    listEnvironments(page?: EnvironmentPageOptions): Promise<EnvironmentPage>;
+    /** Reads one environment and its immutable version summaries. */
+    getEnvironment(id: string): Promise<Environment>;
+    /** Publishes an immutable definition; this non-idempotent registry write is not retried. */
+    publishVersion(environmentId: string, definition: PublishableWorldDefinition): Promise<EnvironmentVersionSummary>;
+    /** Reads a full immutable environment version and generated action catalog. */
+    getVersion(id: string): Promise<WorldVersion>;
+    /** Creates or recovers one fresh isolated world using a stable idempotency key. */
+    createRun(input: CreateRunInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentRun>;
+    /** Reads authoritative current or sealed world state. */
+    getRun(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+        environmentVersionId: string;
+        executionId: string | null;
+        seed: string;
+        status: "open" | "completed" | "abandoned" | "expired";
+        stepCount: number;
+        maxSteps: number;
+        clockNs: string;
+        expiresAt: string;
+        createdAt: string;
+        sealedAt: string | null;
+        stateDigest: string;
+        finalState?: import("./types.js").JsonValue;
+        worldId?: string;
+        lifecycle?: import("./types.js").WorldLifecycle;
+        completingUntil?: string | null;
+        traceExternalId?: string | null;
+        surfaces?: import("./types.js").WorldSurface[];
+        flags?: import("./types.js").WorldFlag[];
+        connection?: null;
+        validity: "environment_incomplete" | "not_assessed";
+        coverageGap: import("./types.js").CoverageGap | null;
+    }>;
+    /** Record a known coverage gap with durable identity; retries reuse the exact request. */
+    recordCoverageGap(runId: string, input: CoverageGapInput): Promise<CoverageGapResult>;
+    /** Invokes an action; repeating an invocation identity replays its recorded result. */
+    act(runId: string, input: ActionInput): Promise<ActionResult>;
+    /** Pages the immutable journal by step ordinal. */
+    listSteps(runId: string, page?: StepPageOptions): Promise<StepPage>;
+    /** Seals a world as completed or abandoned and freezes its evidence. */
+    finishRun(runId: string, input: FinishRunInput): Promise<SealedRun>;
+    /** Reads a sealed world's evaluator-only evidence with the project key; a world token never
+     * can. An open world answers 409 until it is sealed. */
+    getEvidence(runId: string, options?: WorldEvidenceOptions): Promise<WorldEvidence>;
+}
+/** Creates a typed simulated-environment client. */
+/** Compatibility client using the original REST resource names. */
+export declare class EnvironmentClient extends WorldClient {
+    /** Publishes the definition shapes supported by the compatibility client. */
+    publishVersion(environmentId: string, definition: PublishableEnvironmentDefinition): Promise<EnvironmentVersionSummary>;
+    /** Reads the definition using the compatibility client's original return type. */
+    getVersion(id: string): Promise<EnvironmentVersion>;
+    protected resourcePath(path: string): string;
+}
+/** Creates the compatibility client using the original REST resource names. */
+export declare function createEnvironmentClient(options: EnvironmentClientOptions): EnvironmentClient;
+/** Connection options for the World API client. */
+export type WorldClientOptions = EnvironmentClientOptions;
+/** Creates a World API client using canonical World and instance routes. */
+export declare function createWorldClient(options: WorldClientOptions): WorldClient;
+export { HueEnvironmentError as HueWorldError, isTransientEnvironmentError as isTransientWorldError, };