@hue-run/sdk 0.20.0 → 0.20.2

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/dist/world/world.d.ts

@@ -16,8 +16,9 @@ export declare function worldNow(source?: WorldHandoff | Record<string, string |
 /** 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. */
+ * attempt grants, the project MCP key, invocation and installation tokens, OAuth tokens, trace
+ * import authorizations 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. */

package/dist/world/world.js

@@ -53,8 +53,9 @@ export const HUE_CONTROL_PLANE_VARIABLES = [
     "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. */
+ * attempt grants, the project MCP key, invocation and installation tokens, OAuth tokens, trace
+ * import authorizations 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_",
@@ -64,6 +65,7 @@ export const HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES = [
     "hue_install_",
     "hue_at_",
     "hue_rt_",
+    "hue_it_",
     "hue_oauth_",
 ];
 /** A Hue credential anywhere in a value, including JSON Unicode escapes, not inside a longer word. */

package/package.json

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