@hue-run/sdk 0.1.4 → 0.2.0

package/dist/config.d.ts

@@ -1,4 +1,13 @@
-import type { HueOptions } from "./types.js";
+import type { HueOptions, SharedHueOptions } from "./types.js";
 export declare const MAX_BODY_BYTES: number;
 export declare const MAX_CONTENT_BYTES: number;
-export declare function validateOptions(options: HueOptions): Required<Pick<HueOptions, "apiKey" | "serviceName" | "baseUrl" | "captureContent" | "timeoutMillis">> & HueOptions;
+/** Loopback hostnames that may use plain HTTP without opting in. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** True when a validated origin exports over plain HTTP to a host other than loopback. */
+export declare function isInsecureOrigin(baseUrl: string): boolean;
+export declare function validateOptions(options: HueOptions): HueOptions & Required<Pick<SharedHueOptions, "captureContent" | "baseUrl" | "timeoutMillis" | "maxQueueBytes">> & {
+    /** Project key after validation; empty for a disabled client. */
+    apiKey: string;
+    /** Service name after validation; `hue-disabled` for a disabled client. */
+    serviceName: string;
+};

package/dist/config.js

@@ -1,6 +1,37 @@
 export const MAX_BODY_BYTES = 1024 * 1024;
 export const MAX_CONTENT_BYTES = 256 * 1024;
+/** Loopback hostnames that may use plain HTTP without opting in. */
+export function isLoopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** True when a validated origin exports over plain HTTP to a host other than loopback. */
+export function isInsecureOrigin(baseUrl) {
+    const url = new URL(baseUrl);
+    return url.protocol === "http:" && !isLoopbackHost(url.hostname);
+}
+// The return type stays anonymous: HueTransport.options exposes it through ReturnType, and the
+// API reference must not reference a name that is not part of the public entry points.
 export function validateOptions(options) {
+    if (options.enabled !== undefined && typeof options.enabled !== "boolean")
+        throw new TypeError("enabled must be a boolean");
+    if (options.enabled === false) {
+        // The kill switch exports nothing, so the content decision defaults to metadata-only. The
+        // diagnostics hook stays attached so a disabled client can still report why it is off.
+        if (options.captureContent !== undefined && typeof options.captureContent !== "boolean")
+            throw new TypeError("captureContent must be a boolean");
+        return {
+            ...(typeof options.onExportIssue === "function"
+                ? { onExportIssue: options.onExportIssue }
+                : {}),
+            captureContent: options.captureContent ?? false,
+            enabled: false,
+            apiKey: "",
+            serviceName: "hue-disabled",
+            baseUrl: "https://app.hue.run",
+            timeoutMillis: 10000,
+            maxQueueBytes: 8 * 1024 * 1024,
+        };
+    }
     if (typeof options.captureContent !== "boolean")
         throw new TypeError("Choose captureContent explicitly: true or false");
     if (typeof options.apiKey !== "string" ||
@@ -13,6 +44,13 @@ export function validateOptions(options) {
         !options.serviceName.trim() ||
         options.serviceName.length > 256)
         throw new TypeError("A serviceName of 1–256 characters is required");
+    if (options.allowInsecureHttp !== undefined && typeof options.allowInsecureHttp !== "boolean")
+        throw new TypeError("allowInsecureHttp must be a boolean");
+    if (options.resourceAttributes !== undefined &&
+        (options.resourceAttributes === null ||
+            typeof options.resourceAttributes !== "object" ||
+            Array.isArray(options.resourceAttributes)))
+        throw new TypeError("resourceAttributes must be an object of attribute values");
     let url;
     try {
         url = new URL(options.baseUrl ?? "https://app.hue.run");
@@ -20,13 +58,21 @@ export function validateOptions(options) {
     catch {
         throw new TypeError("Invalid Hue baseUrl");
     }
-    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
-    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
-        throw new TypeError("Hue requires HTTPS except for a loopback development server");
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw new TypeError("Hue baseUrl must use https, or http for a loopback development server");
+    if (url.protocol === "http:" &&
+        !isLoopbackHost(url.hostname) &&
+        options.allowInsecureHttp !== true)
+        throw new TypeError("Hue requires HTTPS except for a loopback development server; set allowInsecureHttp: true to export over plain HTTP to another host");
     if (url.username || url.password || url.pathname !== "/" || url.search || url.hash)
         throw new TypeError("Hue baseUrl must be an origin without credentials, a path, query parameters or fragments");
     const timeoutMillis = options.timeoutMillis ?? 10000;
     if (!Number.isInteger(timeoutMillis) || timeoutMillis < 100 || timeoutMillis > 60000)
         throw new TypeError("timeoutMillis must be 100–60000");
-    return { ...options, baseUrl: url.origin, timeoutMillis };
+    const maxQueueBytes = options.maxQueueBytes ?? 8 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxQueueBytes) ||
+        maxQueueBytes < 1024 ||
+        maxQueueBytes > 64 * 1024 * 1024)
+        throw new TypeError("maxQueueBytes must be 1024–67108864");
+    return { ...options, baseUrl: url.origin, timeoutMillis, maxQueueBytes };
 }

package/dist/environment/client.d.ts

@@ -0,0 +1,73 @@
+import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, EnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions } 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;
+    constructor(
+    /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
+    status?: number | undefined);
+}
+/** Typed client for authored environments, isolated runs and immutable journals. */
+export declare class EnvironmentClient {
+    /** Validated Hue origin. */
+    readonly baseUrl: string;
+    private readonly apiKey;
+    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: EnvironmentDefinition): 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): 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;
+        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>;
+}
+/** Creates a typed simulated-environment client. */
+export declare function createEnvironmentClient(options: EnvironmentClientOptions): EnvironmentClient;

package/dist/environment/client.js

@@ -0,0 +1,209 @@
+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;
+    constructor(
+    /** HTTP status when Hue answered; absent for transport, timeout or parse failure. */
+    status) {
+        super(status
+            ? `Hue environment request failed (HTTP ${status})`
+            : "Hue environment connection or response failed");
+        this.status = status;
+        this.name = "HueEnvironmentError";
+    }
+}
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+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) {
+        let response;
+        try {
+            response = await fetch(`${this.baseUrl}/api/v1${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...(payload ? { "Content-Type": "application/json" } : {}),
+                },
+                body: payload,
+                redirect: "error",
+                signal: AbortSignal.timeout(this.timeoutMillis),
+            });
+        }
+        catch {
+            throw new HueEnvironmentError();
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new HueEnvironmentError(response.status);
+        }
+        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) {
+        // 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);
+            }
+            catch (error) {
+                if (!(error instanceof HueEnvironmentError))
+                    throw error;
+                const recoverable = error.status === undefined || RETRYABLE.has(error.status);
+                if (!recoverable || attempt >= this.maxAttempts)
+                    throw error;
+                const backoff = Math.min(100 * 2 ** (attempt - 1), 2000);
+                await new Promise((resolve) => setTimeout(resolve, backoff + Math.random() * backoff));
+            }
+        }
+    }
+    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");
+        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) {
+        const run = await this.request("GET", `/environment-runs/${uuid(runId)}`);
+        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);
+    }
+}
+/** Creates a typed simulated-environment client. */
+export function createEnvironmentClient(options) {
+    return new EnvironmentClient(options);
+}

package/dist/environment/tools.d.ts

@@ -0,0 +1,30 @@
+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. */
+export declare function bindEnvironmentTools(options: BindEnvironmentToolsOptions): Record<string, EnvironmentTool>;

package/dist/environment/tools.js

@@ -0,0 +1,24 @@
+import { randomUUID } from "node:crypto";
+/** Binds a run's generated catalog to plain local callables without changing the agent framework. */
+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,
+                });
+            },
+        };
+    }
+    return tools;
+}