@hue-run/sdk 0.19.0 → 0.20.0

package/dist/cli/listen.js

@@ -5,7 +5,7 @@ import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
 import { resolve } from "node:path";
 import { parseArgs, parseEnv } from "node:util";
-import { HUE_CONTROL_PLANE_VARIABLES } from "../environment/world.js";
+import { HUE_CONTROL_PLANE_VARIABLES } from "../world/world.js";
 import { scrubCredentialText } from "../tool-definitions.js";
 import { sdkVersion } from "../version.js";
 import { envFileArgument, envFileOptions } from "./env-file.js";

package/dist/environment/client.d.ts

@@ -1,95 +1,2 @@
-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";
-/** 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);
-}
-/** 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 EnvironmentClient {
-    #private;
-    /** Validated Hue origin. */
-    readonly baseUrl: string;
-    private readonly timeoutMillis;
-    private readonly maxAttempts;
-    constructor(options: EnvironmentClientOptions);
-    private send;
-    private request;
-    private requestOnce;
-    private page;
-    /** 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: PublishableEnvironmentDefinition): Promise<EnvironmentVersionSummary>;
-    /** Reads a full immutable environment version and generated action catalog. */
-    getVersion(id: string): Promise<EnvironmentVersion>;
-    /** Creates or recovers one fresh isolated world using a stable idempotency key. */
-    createRun(input: CreateRunInput): 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. */
-export declare function createEnvironmentClient(options: EnvironmentClientOptions): EnvironmentClient;
+/** Compatibility entry point. Use the world module. */
+export * from "../world/client.js";

package/dist/environment/client.js

@@ -1,283 +1,2 @@
-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 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 EnvironmentClient {
-    /** 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;
-    }
-    async send(method, path, payload, options = {}) {
-        let response;
-        try {
-            const timeout = AbortSignal.timeout(this.timeoutMillis);
-            response = await fetch(`${this.baseUrl}/api/v1${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();
-        }
-    }
-    async request(method, path, body, options = {}) {
-        // 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));
-        for (let attempt = 1;; attempt++) {
-            try {
-                return await this.send(method, path, payload, options);
-            }
-            catch (error) {
-                if (!(error instanceof HueEnvironmentError))
-                    throw error;
-                if (options.signal?.aborted)
-                    throw error;
-                if (!isTransientEnvironmentError(error) || attempt >= this.maxAttempts)
-                    throw error;
-                // Hue's admission refusals say how long to wait; anything else backs off.
-                const backoff = Math.min(100 * 2 ** (attempt - 1), 2000);
-                const wait = error.retryAfterMs ?? backoff + Math.random() * backoff;
-                await new Promise((resolve, reject) => {
-                    const timer = setTimeout(() => {
-                        options.signal?.removeEventListener("abort", abort);
-                        resolve();
-                    }, wait);
-                    const abort = () => {
-                        clearTimeout(timer);
-                        options.signal?.removeEventListener("abort", abort);
-                        reject(new HueEnvironmentError());
-                    };
-                    if (options.signal?.aborted)
-                        abort();
-                    else
-                        options.signal?.addEventListener("abort", abort, { once: true });
-                });
-            }
-        }
-    }
-    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 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) {
-        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) }),
-        });
-    }
-    /** 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. */
-export function createEnvironmentClient(options) {
-    return new EnvironmentClient(options);
-}
+/** Compatibility entry point. Use the world module. */
+export * from "../world/client.js";

package/dist/environment/tools.d.ts

@@ -1,35 +1,2 @@
-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>;
+/** Compatibility entry point. Use the world module. */
+export * from "../world/tools.js";

package/dist/environment/tools.js

@@ -1,30 +1,2 @@
-import { randomUUID } from "node:crypto";
-/**
- * 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 function bindEnvironmentTools(options) {
-    const tools = {};
-    for (const action of options.run.actions) {
-        tools[action.name] = {
-            name: action.name,
-            ...(action.description === undefined ? {} : { description: action.description }),
-            inputSchema: action.inputSchema,
-            execute: async (args = {}) => {
-                const invocationId = options.invocationId?.(action.name) ?? randomUUID();
-                const execute = async () => (await options.client.act(options.run.id, {
-                    invocationId,
-                    action: action.name,
-                    args,
-                })).observation;
-                return options.hue.tool(action.name, args, execute, {
-                    parentContext: options.parentContext,
-                    ...(action.mcp === undefined ? {} : { mcp: action.mcp }),
-                });
-            },
-        };
-    }
-    return tools;
-}
+/** Compatibility entry point. Use the world module. */
+export * from "../world/tools.js";