@hue-run/sdk 0.19.1 → 0.20.0

package/dist/world/client.js

@@ -0,0 +1,368 @@
+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. */
+export class HueEnvironmentError extends Error {
+    status;
+    retryAfterMs;
+    diagnostic;
+    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) {
+        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.name = "HueEnvironmentError";
+    }
+}
+const DIAGNOSTIC = /^[a-z_]{1,64}$/;
+/** The response's diagnostic code, or undefined when absent or invalid. */
+function diagnosticOf(response) {
+    const value = response.headers.get("x-hue-diagnostic");
+    return value !== null && DIAGNOSTIC.test(value) ? value : undefined;
+}
+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)));
+}
+/** A `Retry-After` longer than this waits this long: Hue asks for a second, never minutes. */
+const MAX_RETRY_AFTER_MS = 10_000;
+const WORLD_PREPARATION_WAIT_MS = 120_000;
+const TRACEPARENT = /^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+/** Version 00 with real identifiers: an all-zero trace or span ID is invalid, and Hue refuses it. */
+function validTraceparent(value) {
+    if (!TRACEPARENT.test(value))
+        return false;
+    const [, traceId, spanId] = value.split("-");
+    return !/^0+$/.test(traceId) && !/^0+$/.test(spanId);
+}
+/** Whole seconds only, as Hue sends them; a date or garbage is ignored. */
+function retryAfterMillis(response) {
+    const header = response.headers.get("retry-after");
+    if (header === null || !/^\d{1,6}$/.test(header.trim()))
+        return undefined;
+    return Math.min(Number(header.trim()) * 1000, MAX_RETRY_AFTER_MS);
+}
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const REQUEST_BOUNDS = { ...valueBounds, bytes: 1024 * 1024 };
+/** The server bounds JSON inside each entity independently, then permits the parsed
+ * definition to contain up to 240 KB. The publication wrapper adds one node/depth
+ * level and a small fixed byte prefix. Aggregate bounds cover every server-valid
+ * 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. */
+export class WorldClient {
+    /** Validated Hue origin. */
+    baseUrl;
+    #apiKey;
+    timeoutMillis;
+    maxAttempts;
+    constructor(options) {
+        const validated = validateOptions({
+            ...options,
+            serviceName: "hue-environments",
+            captureContent: false,
+        });
+        this.baseUrl = validated.baseUrl;
+        this.#apiKey = validated.apiKey;
+        this.timeoutMillis = validated.timeoutMillis;
+        const attempts = options.maxAttempts ?? 4;
+        if (!Number.isInteger(attempts) || attempts < 1 || attempts > 10)
+            throw new RangeError("maxAttempts must be 1–10");
+        this.maxAttempts = attempts;
+    }
+    /** Compatibility clients override only resource routing. */
+    resourcePath(path) {
+        return path
+            .replace(/^\/environments(?=\/|$|\?)/, "/worlds")
+            .replace(/^\/environment-versions(?=\/|$|\?)/, "/world-versions")
+            .replace(/^\/environment-runs(?=\/|$|\?)/, "/instances");
+    }
+    async send(method, path, payload, options = {}) {
+        let response;
+        try {
+            const timeout = AbortSignal.timeout(this.timeoutMillis);
+            response = await fetch(`${this.baseUrl}/api/v1${this.resourcePath(path)}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.#apiKey}`,
+                    ...(payload ? { "Content-Type": "application/json" } : {}),
+                },
+                body: payload,
+                redirect: "error",
+                signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
+            });
+        }
+        catch {
+            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));
+        }
+        try {
+            const reader = response.body?.getReader();
+            if (!reader)
+                throw new Error("Missing response");
+            const chunks = [];
+            let size = 0;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.byteLength;
+                    if (size > MAX_RESPONSE_BYTES)
+                        throw new Error("Oversized response");
+                    chunks.push(value);
+                }
+            }
+            finally {
+                await reader.cancel();
+            }
+            return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        }
+        catch {
+            throw new HueEnvironmentError();
+        }
+    }
+    /** @internal Shared bounded transport for World clients. */
+    async request(method, path, body, options = {}, waitForWorld = false) {
+        // Serialize once: a body this client cannot encode is a caller error that no retry fixes.
+        const payload = body === undefined
+            ? undefined
+            : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), REQUEST_BOUNDS));
+        let ordinaryFailures = 0;
+        let preparingUntil;
+        let preparation;
+        let preparationTimer;
+        try {
+            for (;;) {
+                const signal = preparation
+                    ? options.signal
+                        ? AbortSignal.any([options.signal, preparation.signal])
+                        : preparation.signal
+                    : options.signal;
+                if (signal?.aborted ||
+                    (preparingUntil !== undefined && performance.now() >= preparingUntil))
+                    throw new HueEnvironmentError();
+                try {
+                    return await this.send(method, path, payload, { signal });
+                }
+                catch (error) {
+                    if (!(error instanceof HueEnvironmentError))
+                        throw error;
+                    if (signal?.aborted)
+                        throw error;
+                    const preparing = waitForWorld && error.status === 503 && error.diagnostic === "world_preparing";
+                    let wait;
+                    if (preparing) {
+                        if (preparingUntil === undefined) {
+                            preparingUntil = performance.now() + WORLD_PREPARATION_WAIT_MS;
+                            preparation = new AbortController();
+                            preparationTimer = setTimeout(() => preparation.abort(), WORLD_PREPARATION_WAIT_MS);
+                        }
+                        // A zero Retry-After must not turn preparation into an unbounded busy loop.
+                        wait = Math.max(100, error.retryAfterMs ?? 1000);
+                    }
+                    else {
+                        ordinaryFailures++;
+                        if (!isTransientEnvironmentError(error) || ordinaryFailures >= this.maxAttempts)
+                            throw error;
+                        const backoff = Math.min(100 * 2 ** (ordinaryFailures - 1), 2000);
+                        wait = error.retryAfterMs ?? backoff + Math.random() * backoff;
+                    }
+                    if (preparingUntil !== undefined) {
+                        const remaining = preparingUntil - performance.now();
+                        if (remaining <= 0)
+                            throw error;
+                        wait = Math.min(wait, remaining);
+                    }
+                    const waiting = preparation
+                        ? options.signal
+                            ? AbortSignal.any([options.signal, preparation.signal])
+                            : preparation.signal
+                        : options.signal;
+                    await new Promise((resolve, reject) => {
+                        const timer = setTimeout(() => {
+                            waiting?.removeEventListener("abort", abort);
+                            resolve();
+                        }, wait);
+                        const abort = () => {
+                            clearTimeout(timer);
+                            waiting?.removeEventListener("abort", abort);
+                            reject(new HueEnvironmentError());
+                        };
+                        if (waiting?.aborted)
+                            abort();
+                        else
+                            waiting?.addEventListener("abort", abort, { once: true });
+                    });
+                }
+            }
+        }
+        finally {
+            if (preparationTimer !== undefined)
+                clearTimeout(preparationTimer);
+        }
+    }
+    /** @internal Single-attempt transport for non-idempotent compatibility operations. */
+    requestOnce(method, path, body, bounds = REQUEST_BOUNDS) {
+        const payload = body === undefined
+            ? undefined
+            : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
+        return this.send(method, path, payload);
+    }
+    page(options = {}) {
+        const query = new URLSearchParams();
+        if (options.after)
+            query.set("after", uuid(options.after));
+        if (options.limit !== undefined) {
+            if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100)
+                throw new RangeError("Page limit must be 1–100");
+            query.set("limit", String(options.limit));
+        }
+        return query.size ? `?${query}` : "";
+    }
+    /** Creates an isolated instance from an immutable World version. */
+    createInstance(input, options = {}) {
+        const { worldVersionId, ...runInput } = input;
+        return this.createRun({ ...runInput, environmentVersionId: worldVersionId }, options);
+    }
+    /** Reads current or sealed instance state. */
+    getInstance(instanceId, options = {}) {
+        return this.getRun(instanceId, options);
+    }
+    /** Completes or abandons one instance and freezes its evidence. */
+    finishInstance(instanceId, input) {
+        return this.finishRun(instanceId, input);
+    }
+    /** Creates an environment identity; this non-idempotent registry write is not retried. */
+    createEnvironment(input) {
+        return this.requestOnce("POST", "/environments", input);
+    }
+    /** Lists active environment identities. */
+    listEnvironments(page) {
+        return this.request("GET", `/environments${this.page(page)}`);
+    }
+    /** Reads one environment and its immutable version summaries. */
+    getEnvironment(id) {
+        return this.request("GET", `/environments/${uuid(id)}`);
+    }
+    /** Publishes an immutable definition; this non-idempotent registry write is not retried. */
+    publishVersion(environmentId, definition) {
+        return this.requestOnce("POST", `/environments/${uuid(environmentId)}/versions`, { definition }, ENVIRONMENT_PUBLICATION_BOUNDS);
+    }
+    /** Reads a full immutable environment version and generated action catalog. */
+    getVersion(id) {
+        return this.request("GET", `/environment-versions/${uuid(id)}`);
+    }
+    /** Creates or recovers one fresh isolated world using a stable idempotency key. */
+    createRun(input, options = {}) {
+        if (input.maxSteps !== undefined &&
+            (!Number.isInteger(input.maxSteps) || input.maxSteps < 1 || input.maxSteps > 500))
+            throw new RangeError("maxSteps must be 1–500");
+        if (input.ttlSeconds !== undefined &&
+            (!Number.isInteger(input.ttlSeconds) || input.ttlSeconds < 1 || input.ttlSeconds > 86_400))
+            throw new RangeError("ttlSeconds must be 1–86400");
+        if (input.seed !== undefined && !/^[a-f0-9]{32}$/.test(input.seed))
+            throw new TypeError("Seed must be 32 lowercase hexadecimal characters");
+        if (input.traceparent !== undefined && !validTraceparent(input.traceparent))
+            throw new TypeError("traceparent must be a version-00 W3C trace context");
+        if (input.agentRevision !== undefined &&
+            (typeof input.agentRevision !== "string" ||
+                input.agentRevision.length < 1 ||
+                input.agentRevision.length > 256))
+            throw new RangeError("agentRevision must be 1–256 characters");
+        return this.request("POST", "/environment-runs", {
+            ...input,
+            environmentVersionId: uuid(input.environmentVersionId),
+            ...(input.executionId === undefined ? {} : { executionId: uuid(input.executionId) }),
+        }, options, true);
+    }
+    /** Reads authoritative current or sealed world state. */
+    async getRun(runId, options = {}) {
+        const run = await this.request("GET", `/environment-runs/${uuid(runId)}`, undefined, options);
+        return { validity: "not_assessed", coverageGap: null, ...run };
+    }
+    /** Record a known coverage gap with durable identity; retries reuse the exact request. */
+    recordCoverageGap(runId, input) {
+        uuid(input.idempotencyKey);
+        if (!input.args || typeof input.args !== "object" || Array.isArray(input.args))
+            throw new TypeError("Coverage gap arguments must be a JSON object");
+        json(input.args, { ...valueBounds, bytes: 16_000 });
+        return this.request("POST", `/environment-runs/${uuid(runId)}/coverage-gap`, input);
+    }
+    /** Invokes an action; repeating an invocation identity replays its recorded result. */
+    act(runId, input) {
+        return this.request("POST", `/environment-runs/${uuid(runId)}/actions`, {
+            ...input,
+            args: input.args ?? {},
+        });
+    }
+    /** Pages the immutable journal by step ordinal. */
+    listSteps(runId, page = {}) {
+        const query = new URLSearchParams();
+        if (page.after !== undefined) {
+            if (!Number.isInteger(page.after) || page.after < -1)
+                throw new RangeError("Step cursor must be an ordinal");
+            query.set("after", String(page.after));
+        }
+        if (page.limit !== undefined) {
+            if (!Number.isInteger(page.limit) || page.limit < 1 || page.limit > 100)
+                throw new RangeError("Page limit must be 1–100");
+            query.set("limit", String(page.limit));
+        }
+        return this.request("GET", `/environment-runs/${uuid(runId)}/steps${query.size ? `?${query}` : ""}`);
+    }
+    /** Seals a world as completed or abandoned and freezes its evidence. */
+    finishRun(runId, input) {
+        return this.request("POST", `/environment-runs/${uuid(runId)}/finish`, input);
+    }
+    /** 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, options = {}) {
+        const query = new URLSearchParams();
+        if (options.section !== undefined) {
+            if (!["all", "start", "end", "diff", "ledger"].includes(options.section))
+                throw new TypeError("Evidence section must be all, start, end, diff or ledger");
+            query.set("section", options.section);
+        }
+        if (options.bodies !== undefined)
+            query.set("bodies", options.bodies ? "true" : "false");
+        return this.request("GET", `/environment-runs/${uuid(runId)}/evidence${query.size ? `?${query}` : ""}`);
+    }
+}
+/** Creates a typed simulated-environment client. */
+/** Compatibility client using the original REST resource names. */
+export class EnvironmentClient extends WorldClient {
+    /** Publishes the definition shapes supported by the compatibility client. */
+    publishVersion(environmentId, definition) {
+        return super.publishVersion(environmentId, definition);
+    }
+    /** Reads the definition using the compatibility client's original return type. */
+    getVersion(id) {
+        return super.getVersion(id);
+    }
+    resourcePath(path) {
+        return path;
+    }
+}
+/** Creates the compatibility client using the original REST resource names. */
+export function createEnvironmentClient(options) {
+    return new EnvironmentClient(options);
+}
+/** Creates a World API client using canonical World and instance routes. */
+export function createWorldClient(options) {
+    return new WorldClient(options);
+}
+export { HueEnvironmentError as HueWorldError, isTransientEnvironmentError as isTransientWorldError, };

package/dist/world/definitions.d.ts

@@ -0,0 +1,47 @@
+import type { EnvironmentDefinitionV1, EnvironmentVersion, JsonValue, PublishableEnvironmentDefinition } from "./types.js";
+/** One account binding for any app registered by the Hue deployment. */
+export interface WorldProviderInstance {
+    /** Account-specific key used to select this binding. */
+    providerInstanceKey: string;
+    /** Registered app identifier. The server validates support. */
+    providerId: string;
+    /** Stable synthetic principal for this account connection. */
+    syntheticPrincipalId: string;
+    /** App-owned JSON configuration, validated by that app's simulation package. */
+    configuration: Record<string, JsonValue>;
+    /** Optional registered protocol dialects pinned for this binding. */
+    dialects?: string[];
+}
+/** V1 authored starting-state definition. */
+export type WorldDefinitionV1 = EnvironmentDefinitionV1;
+/** Compatible V1 starting-state definition. */
+export type WorldDefinition = WorldDefinitionV1;
+/** Recorded app credential refusal, optionally restricted to one account binding. */
+export interface WorldCredentialFailure {
+    /** App identity. */
+    provider: string;
+    /** Protocol surface on which the refusal was observed. */
+    surface: string;
+    /** Recorded operation. */
+    operation: string;
+    /** Account binding affected by the refusal. */
+    instance?: string;
+    /** Optional recorded wire result. */
+    result?: Record<string, JsonValue>;
+}
+/** Authored World with arbitrary registered apps and independently identified accounts. */
+export interface WorldDefinitionV2 extends Omit<WorldDefinitionV1, "schemaVersion"> {
+    /** Definition schema discriminator. */
+    schemaVersion: 2;
+    /** App/account bindings. Several entries may use the same provider. */
+    providerInstances: WorldProviderInstance[];
+    /** Recorded credential refusals, independently scoped to app accounts. */
+    credentialFailures?: WorldCredentialFailure[];
+}
+/** Definitions accepted by canonical World publication, including legacy typed carriers. */
+export type PublishableWorldDefinition = WorldDefinitionV1 | WorldDefinitionV2 | PublishableEnvironmentDefinition;
+/** Immutable published World version with an app-agnostic starting-state definition. */
+export interface WorldVersion extends Omit<EnvironmentVersion, "definition"> {
+    /** App/account-aware immutable starting-state definition. */
+    definition: PublishableWorldDefinition;
+}

package/dist/world/definitions.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,117 @@
+/** 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. */
+    namespace: string;
+    /** Full external identifier. */
+    id: string;
+}
+/** Continuously enriched history belonging to one entity in one project. */
+export interface WorldModel {
+    /** Stable identity of this record. */
+    id: string;
+    /** Project owning this World model. */
+    projectId: string;
+    /** Full external identity represented by the model. */
+    entity: WorldEntity;
+    /** Display name. */
+    name: string;
+    /** Creation timestamp in RFC 3339 format. */
+    createdAt: string;
+    /** Last successful instance start, or null when never used. */
+    lastUsedAt: string | null;
+    /** Committed evidence sequence used for reconstruction. */
+    evidenceCutoff: number;
+    /** Publication or erasure state. */
+    status: "ready" | "preparing" | "erased";
+}
+/** One app account bound to a World model. */
+export interface WorldModelAccount {
+    /** Stable identity of this record. */
+    id: string;
+    /** App simulation identifier. */
+    providerId: string;
+    /** Account-specific binding key used by the simulation gateway. */
+    providerInstanceKey: string;
+    /** External account identity. */
+    accountId: string;
+    /** Connection generation that separates account rebinding. */
+    generation: number;
+    /** Optional tenant or workspace scope within the external account. */
+    scope?: string;
+    /** Stable simulation principal for this account binding. */
+    syntheticPrincipalId: string;
+}
+/** Immutable reconstructed starting state at a represented time and evidence cutoff. */
+export interface StartingWorld {
+    /** Stable identity of this record. */
+    id: string;
+    /** World model from which this state was reconstructed. */
+    modelId: string;
+    /** Represented time as an ISO 8601 timestamp with a timezone. */
+    at: string;
+    /** Committed evidence sequence used for reconstruction. */
+    evidenceCutoff: number;
+    /** Immutable starting-state digest, or null while preparation is incomplete. */
+    digest: string | null;
+    /** Publication or erasure state. */
+    status: "ready" | "preparing";
+}
+/** Bounded pagination over World models or their accounts. */
+export interface WorldModelPageOptions {
+    /** Opaque cursor returned by the previous page. */
+    after?: string;
+    /** Maximum entries in the page, from 1 to 100. */
+    limit?: number;
+}
+/** One page of World models. */
+export interface WorldModelPage {
+    /** Entries in this page. */
+    items: WorldModel[];
+    /** Cursor for the next page, omitted when no further entries remain. */
+    nextCursor?: string;
+}
+/** One page of account bindings. */
+export interface WorldModelAccountPage {
+    /** Entries in this page. */
+    items: WorldModelAccount[];
+    /** Cursor for the next page, omitted when no further entries remain. */
+    nextCursor?: string;
+}
+/** Creates or retrieves the World model for an entity. */
+export interface CreateWorldModelInput {
+    /** Full external identity represented by the model. */
+    entity: WorldEntity;
+    /** Display name. */
+    name?: string;
+}
+/** Starts an isolated instance using the latest completed reconstruction of a chosen time. */
+export interface StartWorldInstanceInput {
+    /** Caller-owned identity reused for retries of this exact operation. */
+    idempotencyKey: string;
+    /** Represented time as an ISO 8601 timestamp with a timezone. */
+    at: string;
+    /** Requested instance lifetime in seconds. */
+    ttlSeconds?: number;
+}
+/** Reproduces an earlier starting World under a durable request identity. */
+export interface ReproduceWorldInstanceInput {
+    /** Caller-owned identity reused for retries of this exact operation. */
+    idempotencyKey: string;
+    /** Requested instance lifetime in seconds. */
+    ttlSeconds?: number;
+}
+/** One World model returned by create or get. */
+export interface WorldModelResult {
+    /** Entity history and its current committed evidence sequence. */
+    worldModel: WorldModel;
+}
+/** One reconstructed starting World without a running instance. */
+export interface StartingWorldResult {
+    /** Immutable starting state, or an explicit preparing state. */
+    world: StartingWorld;
+}
+/** Acknowledgement that the World model has been erased. */
+export interface ErasedWorldModel {
+    /** Successful erasure acknowledgement. */
+    erased: true;
+}

package/dist/world/model-types.js

@@ -0,0 +1 @@
+export {};

package/dist/world/models.d.ts

@@ -0,0 +1,40 @@
+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 { WorldHandoff } from "./types.js";
+/** Reconstructed starting World and its isolated runtime connection. */
+export interface WorldInstanceResult {
+    /** Immutable starting state used by the new instance. */
+    world: StartingWorld;
+    /** Fresh, instance-scoped connection and credentials. */
+    instance: WorldHandoff;
+}
+/** Project-key client for entity histories, reconstructed Worlds and isolated instances. */
+export declare class WorldModelClient extends WorldClient {
+    /** Creates the client without starting a World or instance. */
+    constructor(options: WorldClientOptions);
+    /** Creates or retrieves the model for one full project-scoped entity identity. */
+    createModel(input: CreateWorldModelInput): Promise<WorldModelResult>;
+    /** Lists World models without loading their evidence or runtime state. */
+    listModels(options?: WorldModelPageOptions): Promise<WorldModelPage>;
+    /** Reads a model's identity and committed evidence cutoff. */
+    getModel(modelId: string): Promise<WorldModelResult>;
+    /** Lists account bindings, including multiple accounts of the same app. */
+    listAccounts(modelId: string, options?: WorldModelPageOptions): Promise<WorldModelAccountPage>;
+    /** Reconstructs the chosen time with the latest committed evidence, without starting an instance. */
+    materialize(modelId: string, input: {
+        at: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<StartingWorldResult>;
+    /** Starts one isolated instance, replaying the same request identity after transport failures. */
+    startInstance(modelId: string, input: StartWorldInstanceInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorldInstanceResult>;
+    /** Starts a fresh instance from the original immutable starting World of an earlier instance. */
+    reproduceInstance(instanceId: string, input: ReproduceWorldInstanceInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorldInstanceResult>;
+    /** Revokes and erases a World model. Erased starting Worlds cannot be reproduced. */
+    eraseModel(modelId: string): Promise<ErasedWorldModel>;
+    private modelPage;
+}

package/dist/world/models.js

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto";
+import { uuid } from "../evals/json.js";
+import { WorldClient } from "./client.js";
+/** Project-key client for entity histories, reconstructed Worlds and isolated instances. */
+export class WorldModelClient extends WorldClient {
+    /** Creates the client without starting a World or instance. */
+    constructor(options) {
+        super(options);
+    }
+    /** Creates or retrieves the model for one full project-scoped entity identity. */
+    createModel(input) {
+        return this.request("POST", "/world-models", input);
+    }
+    /** Lists World models without loading their evidence or runtime state. */
+    listModels(options = {}) {
+        return this.request("GET", `/world-models${this.modelPage(options)}`);
+    }
+    /** Reads a model's identity and committed evidence cutoff. */
+    getModel(modelId) {
+        return this.request("GET", `/world-models/${uuid(modelId)}`);
+    }
+    /** Lists account bindings, including multiple accounts of the same app. */
+    listAccounts(modelId, options = {}) {
+        return this.request("GET", `/world-models/${uuid(modelId)}/accounts${this.modelPage(options)}`);
+    }
+    /** Reconstructs the chosen time with the latest committed evidence, without starting an instance. */
+    materialize(modelId, input, options = {}) {
+        return this.request("POST", `/world-models/${uuid(modelId)}/materializations`, { ...input, idempotencyKey: randomUUID() }, options, true);
+    }
+    /** Starts one isolated instance, replaying the same request identity after transport failures. */
+    startInstance(modelId, input, options = {}) {
+        return this.request("POST", `/world-models/${uuid(modelId)}/instances`, input, options, true);
+    }
+    /** Starts a fresh instance from the original immutable starting World of an earlier instance. */
+    reproduceInstance(instanceId, input, options = {}) {
+        return this.request("POST", `/instances/${uuid(instanceId)}/reproduce`, input, options, true);
+    }
+    /** Revokes and erases a World model. Erased starting Worlds cannot be reproduced. */
+    eraseModel(modelId) {
+        return this.request("DELETE", `/world-models/${uuid(modelId)}`);
+    }
+    modelPage(options) {
+        const query = new URLSearchParams();
+        if (options.after !== undefined) {
+            if (typeof options.after !== "string" || !options.after)
+                throw new TypeError("Page cursor must be a nonempty string");
+            query.set("after", options.after);
+        }
+        if (options.limit !== undefined) {
+            if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100)
+                throw new RangeError("Page limit must be 1–100");
+            query.set("limit", String(options.limit));
+        }
+        return query.size ? `?${query}` : "";
+    }
+}

package/dist/world/tools.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from "@opentelemetry/api";
+import type { HueClient } from "../client.js";
+import type { EnvironmentClient } from "./client.js";
+import type { ActionSchema, EnvironmentRun, JsonValue, Observation } from "./types.js";
+/** Framework-neutral callable generated from one environment action. */
+export interface EnvironmentTool {
+    /** Tool name. */
+    name: string;
+    /** Agent-visible description. */
+    description?: string;
+    /** JSON Schema input contract. */
+    inputSchema: ActionSchema;
+    /** Executes the action and resolves with the world's observation. */
+    execute(args?: Record<string, JsonValue>): Promise<Observation>;
+}
+/** Dependencies and tracing context for {@link bindEnvironmentTools}. */
+export interface BindEnvironmentToolsOptions {
+    /** Hue client used to record each action as tool telemetry. */
+    hue: HueClient;
+    /** Environment client bound to the same Hue origin. */
+    client: Pick<EnvironmentClient, "act">;
+    /** Fresh environment run whose closed catalog becomes callables. */
+    run: EnvironmentRun;
+    /** Optional parent span context for generated tool spans. */
+    parentContext?: Context;
+    /** Optional durable invocation-ID factory for caller-owned resume state. */
+    invocationId?(action: string): string;
+}
+/**
+ * Binds a run's generated catalog to plain local callables without changing the agent
+ * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` and `hue.mcp.provider` /
+ * `hue.mcp.surface` so a generic verb is attributed to that MCP server and Hue surface.
+ */
+export declare function bindEnvironmentTools(options: BindEnvironmentToolsOptions): Record<string, EnvironmentTool>;