@hue-run/sdk 0.20.0 → 0.20.1

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.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.1`, `@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.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
+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
 ```
 
 `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.20.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.1.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.20.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.1.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.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>
+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>
 ```
 
 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.20.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

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.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
+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
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3

package/WORLDS.md

@@ -13,8 +13,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.
 
-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
+A World model is retained entity history. A World is a reconstructed starting state. A World
+instance is an isolated running copy of that state. Starting another World instance does not
+share the first World instance's changes. The handoff's
 legacy `worldId` field identifies the runtime instance, not a durable World model.
 
 ## Reconstruct a user's World
@@ -52,6 +53,14 @@ reports that the World is preparing. Retries preserve the same request bytes and
 Other failures keep the client's `maxAttempts` limit. Pass `{ signal }` as the last options
 argument to cancel a preparation wait or an active request.
 
+When the service reports preparation progress, `worldModel.processing` distinguishes retained
+evidence from indexed evidence. A start's `preparation` also includes the selected evidence
+cutoff. `HueWorldError.preparation` exposes the same bounded progress on a preparation refusal.
+Insufficient evidence and processing limits stop identical retries. Useful later evidence or an
+interpreter update can prepare the same unfinished request automatically. Retrying its original
+idempotency key starts the first usable World selected for that request. Preparation requires no
+review or publish action.
+
 `listModels` and `listAccounts` accept `after` and `limit` for pagination. Use each account's
 `providerInstanceKey` to distinguish connections, including several accounts for one app.
 
@@ -112,7 +121,9 @@ OAuth tokens or provider credentials in these fields.
 
 ## Publish an authored World
 
-`createWorldClient` also publishes authored definitions and starts instances from their
+`createWorldClient` uses `createWorld`, `listWorlds` and `getWorld` for World identities.
+The compatibility names `createEnvironment`, `listEnvironments` and `getEnvironment` remain
+available. The client also publishes authored definitions and starts World 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.

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

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

package/dist/world/client.d.ts

@@ -1,3 +1,4 @@
+import { type WorldPreparationProgress } from "./readiness.js";
 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}. */
@@ -19,13 +20,17 @@ export declare class HueEnvironmentError extends Error {
     readonly retryAfterMs?: number | undefined;
     /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
     readonly diagnostic?: string | undefined;
+    /** Bounded, sanitized progress for a World preparation refusal. */
+    readonly preparation?: WorldPreparationProgress | 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);
+    diagnostic?: string | undefined, 
+    /** Bounded, sanitized progress for a World preparation refusal. */
+    preparation?: WorldPreparationProgress | undefined);
 }
 /** Starts one isolated instance from an immutable World version. */
 export interface CreateInstanceInput extends Omit<CreateRunInput, "environmentVersionId"> {
@@ -34,7 +39,7 @@ export interface CreateInstanceInput extends Omit<CreateRunInput, "environmentVe
 }
 /** 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. */
+/** Typed client for authored Worlds, isolated World instances and immutable journals. */
 export declare class WorldClient {
     #private;
     /** Validated Hue origin. */
@@ -79,6 +84,12 @@ export declare class WorldClient {
     }>;
     /** Completes or abandons one instance and freezes its evidence. */
     finishInstance(instanceId: string, input: FinishRunInput): Promise<SealedRun>;
+    /** Creates a World identity using the client's resource routes. */
+    createWorld(input: EnvironmentIdentity): Promise<EnvironmentSummary>;
+    /** Lists active Worlds. */
+    listWorlds(page?: EnvironmentPageOptions): Promise<EnvironmentPage>;
+    /** Reads a World and its immutable version summaries. */
+    getWorld(id: string): Promise<Environment>;
     /** Creates an environment identity; this non-idempotent registry write is not retried. */
     createEnvironment(input: EnvironmentIdentity): Promise<EnvironmentSummary>;
     /** Lists active environment identities. */

package/dist/world/client.js

@@ -1,3 +1,4 @@
+import { readWorldPreparation, TERMINAL_WORLD_DIAGNOSTICS, } from "./readiness.js";
 import { validateOptions } from "../config.js";
 import { aggregateBounds, json, uuid, valueBounds } from "../evals/json.js";
 /** Sanitized environment API failure that never includes response text or credentials. */
@@ -5,19 +6,23 @@ export class HueEnvironmentError extends Error {
     status;
     retryAfterMs;
     diagnostic;
+    preparation;
     constructor(
     /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
     status, 
     /** Hue's `Retry-After` in milliseconds, bounded, when a 429 or 503 carried one. */
     retryAfterMs, 
     /** The server's `X-Hue-Diagnostic` code, when it is a short snake-case value. */
-    diagnostic) {
+    diagnostic, 
+    /** Bounded, sanitized progress for a World preparation refusal. */
+    preparation) {
         super(status
             ? `Hue environment request failed (HTTP ${status}${diagnostic ? `, ${diagnostic}` : ""})`
             : "Hue environment connection or response failed");
         this.status = status;
         this.retryAfterMs = retryAfterMs;
         this.diagnostic = diagnostic;
+        this.preparation = preparation;
         this.name = "HueEnvironmentError";
     }
 }
@@ -31,7 +36,8 @@ const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
 /** A connection failure or a status the client retries; seal polling continues through these. */
 export function isTransientEnvironmentError(error) {
     return (error instanceof HueEnvironmentError &&
-        (error.status === undefined || RETRYABLE.has(error.status)));
+        (error.status === undefined || RETRYABLE.has(error.status)) &&
+        !(error.status === 503 && TERMINAL_WORLD_DIAGNOSTICS.has(error.diagnostic ?? "")));
 }
 /** A `Retry-After` longer than this waits this long: Hue asks for a second, never minutes. */
 const MAX_RETRY_AFTER_MS = 10_000;
@@ -59,7 +65,7 @@ const REQUEST_BOUNDS = { ...valueBounds, bytes: 1024 * 1024 };
  * definition without relaxing action/run request envelopes.
  */
 const ENVIRONMENT_PUBLICATION_BOUNDS = aggregateBounds(240_000 + 32);
-/** Typed client for authored environments, isolated runs and immutable journals. */
+/** Typed client for authored Worlds, isolated World instances and immutable journals. */
 export class WorldClient {
     /** Validated Hue origin. */
     baseUrl;
@@ -106,8 +112,9 @@ export class WorldClient {
             throw new HueEnvironmentError();
         }
         if (!response.ok) {
-            await response.body?.cancel();
-            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined, diagnosticOf(response));
+            const diagnostic = diagnosticOf(response);
+            const preparation = await readWorldPreparation(response, diagnostic);
+            throw new HueEnvironmentError(response.status, response.status === 429 || response.status === 503 ? retryAfterMillis(response) : undefined, diagnostic, preparation);
         }
         try {
             const reader = response.body?.getReader();
@@ -246,6 +253,18 @@ export class WorldClient {
     finishInstance(instanceId, input) {
         return this.finishRun(instanceId, input);
     }
+    /** Creates a World identity using the client's resource routes. */
+    createWorld(input) {
+        return this.createEnvironment(input);
+    }
+    /** Lists active Worlds. */
+    listWorlds(page) {
+        return this.listEnvironments(page);
+    }
+    /** Reads a World and its immutable version summaries. */
+    getWorld(id) {
+        return this.getEnvironment(id);
+    }
     /** Creates an environment identity; this non-idempotent registry write is not retried. */
     createEnvironment(input) {
         return this.requestOnce("POST", "/environments", input);

package/dist/world/model-types.d.ts

@@ -1,3 +1,5 @@
+import type { WorldModelProcessing, WorldPreparationProgress } from "./readiness.js";
+export type { WorldModelProcessing, WorldPreparationProgress } from "./readiness.js";
 /** Project-scoped identity of the user or entity represented by a World model. */
 export interface WorldEntity {
     /** Identifier namespace, such as the application's user namespace. */
@@ -21,8 +23,10 @@ export interface WorldModel {
     lastUsedAt: string | null;
     /** Committed evidence sequence used for reconstruction. */
     evidenceCutoff: number;
-    /** Publication or erasure state. */
+    /** Legacy retention or erasure state. Read `processing` for current indexing progress. */
     status: "ready" | "preparing" | "erased";
+    /** Retained and indexed progress, when reported by Hue. */
+    processing?: WorldModelProcessing;
 }
 /** One app account bound to a World model. */
 export interface WorldModelAccount {
@@ -53,7 +57,7 @@ export interface StartingWorld {
     evidenceCutoff: number;
     /** Immutable starting-state digest, or null while preparation is incomplete. */
     digest: string | null;
-    /** Publication or erasure state. */
+    /** Starting-state preparation status. */
     status: "ready" | "preparing";
 }
 /** Bounded pagination over World models or their accounts. */
@@ -109,6 +113,8 @@ export interface WorldModelResult {
 export interface StartingWorldResult {
     /** Immutable starting state, or an explicit preparing state. */
     world: StartingWorld;
+    /** Progress of this requested starting World, when reported by Hue. */
+    preparation?: WorldPreparationProgress;
 }
 /** Acknowledgement that the World model has been erased. */
 export interface ErasedWorldModel {

package/dist/world/models.d.ts

@@ -1,5 +1,5 @@
 import { WorldClient, type WorldClientOptions } from "./client.js";
-import type { CreateWorldModelInput, WorldModelResult, StartingWorldResult, ErasedWorldModel, ReproduceWorldInstanceInput, StartingWorld, StartWorldInstanceInput, WorldModelAccountPage, WorldModelPage, WorldModelPageOptions } from "./model-types.js";
+import type { CreateWorldModelInput, WorldModelResult, StartingWorldResult, ErasedWorldModel, ReproduceWorldInstanceInput, StartingWorld, StartWorldInstanceInput, WorldModelAccountPage, WorldModelPage, WorldModelPageOptions, WorldPreparationProgress } from "./model-types.js";
 import type { WorldHandoff } from "./types.js";
 /** Reconstructed starting World and its isolated runtime connection. */
 export interface WorldInstanceResult {
@@ -7,6 +7,8 @@ export interface WorldInstanceResult {
     world: StartingWorld;
     /** Fresh, instance-scoped connection and credentials. */
     instance: WorldHandoff;
+    /** Progress of this requested starting World, when reported by Hue. */
+    preparation?: WorldPreparationProgress;
 }
 /** Project-key client for entity histories, reconstructed Worlds and isolated instances. */
 export declare class WorldModelClient extends WorldClient {

package/dist/world/readiness.d.ts

@@ -0,0 +1,18 @@
+/** Progress of one requested starting World. */
+export interface WorldPreparationProgress {
+    /** Whether the request is preparing, usable, or waiting for changed evidence or dependencies. */
+    state: "preparing" | "insufficient_evidence" | "processing_limit" | "dependency_unavailable" | "ready";
+    /** Evidence cutoff selected for this request. */
+    selectedEvidenceCutoff: number;
+    /** Latest retained evidence cutoff. */
+    retainedEvidenceCutoff: number;
+    /** Latest indexed evidence cutoff for the current interpretation. */
+    readyEvidenceCutoff: number;
+    /** Whether retained evidence is still waiting for indexing. */
+    pendingEvidence: boolean;
+}
+/** Retained and indexed progress of an entity history. */
+export interface WorldModelProcessing extends Omit<WorldPreparationProgress, "state" | "selectedEvidenceCutoff"> {
+    /** Indexing progress; a requested represented time may still lack required evidence. */
+    state: "indexed" | "preparing" | "insufficient_evidence" | "processing_limit" | "dependency_unavailable";
+}

package/dist/world/readiness.js

@@ -0,0 +1,69 @@
+const diagnosticStates = {
+    world_preparing: "preparing",
+    world_insufficient_evidence: "insufficient_evidence",
+    world_processing_limit: "processing_limit",
+    world_dependency_unavailable: "dependency_unavailable",
+};
+/** @internal Only numeric progress and an allowlisted state cross the error boundary. */
+export async function readWorldPreparation(response, diagnostic) {
+    if (response.status !== 503 || diagnostic === undefined || !(diagnostic in diagnosticStates)) {
+        await response.body?.cancel().catch(() => { });
+        return undefined;
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return undefined;
+    try {
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 16 * 1024)
+                return undefined;
+            chunks.push(value);
+        }
+        const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!body || typeof body !== "object" || !("preparation" in body))
+            return undefined;
+        const value = body.preparation;
+        if (!value || typeof value !== "object")
+            return undefined;
+        const { state, selectedEvidenceCutoff: selected, retainedEvidenceCutoff: retained, readyEvidenceCutoff: ready, pendingEvidence, } = value;
+        const expectedState = diagnosticStates[diagnostic];
+        if (expectedState === undefined ||
+            state !== expectedState ||
+            !Number.isSafeInteger(selected) ||
+            !Number.isSafeInteger(retained) ||
+            !Number.isSafeInteger(ready) ||
+            typeof selected !== "number" ||
+            typeof retained !== "number" ||
+            typeof ready !== "number" ||
+            selected < 0 ||
+            ready < 0 ||
+            selected > retained ||
+            ready > retained ||
+            pendingEvidence !== retained > ready)
+            return undefined;
+        return {
+            state: expectedState,
+            selectedEvidenceCutoff: selected,
+            retainedEvidenceCutoff: retained,
+            readyEvidenceCutoff: ready,
+            pendingEvidence,
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+/** @internal These failures require changed evidence or processing, not another identical call. */
+export const TERMINAL_WORLD_DIAGNOSTICS = new Set([
+    "world_insufficient_evidence",
+    "world_processing_limit",
+]);

package/package.json

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