@hue-run/sdk 0.19.0 → 0.20.0

package/dist/inline-files.js

@@ -102,6 +102,74 @@ function base64Header(header) {
     return semicolon !== -1 && `${header.slice(semicolon)};`.includes(";base64;");
 }
 const hexPair = /^[0-9A-Fa-f]{2}$/;
+/** Raw 16-bit PCM media types and the byte order of their samples, as Hue's reader names them. */
+const pcmEndian = new Map([
+    ["audio/l16", "big"],
+    ["audio/pcm", "little"],
+    ["audio/x-pcm", "little"],
+]);
+/** One media type parameter (`name=value`, the value a token or a quoted string) or an empty one,
+ * then the `;` that ends it or the end of the type (RFC 9110 section 8.3.1). */
+const pcmParameter = /[ \t]*(?:([!#$%&'*+.^_`|~0-9A-Za-z-]+)[ \t]*=[ \t]*([!#$%&'*+.^_`|~0-9A-Za-z-]+|"(?:[^"\\]|\\.)*")[ \t]*)?(;|$)/y;
+/** A whole number written in decimal digits alone, within `[min, max]`. */
+function wholeIn(value, min, max) {
+    if (value === undefined || !/^\d{1,7}$/.test(value))
+        return undefined;
+    const number = Number(value);
+    return number >= min && number <= max ? number : undefined;
+}
+/**
+ * The canonical media type of raw 16-bit PCM whose type declares its format, as Hue's reader reads
+ * one and names it: `audio/pcm;rate=<Hz>;channels=<n>` for little-endian `audio/pcm` and
+ * `audio/x-pcm`, `audio/L16;rate=<Hz>;channels=<n>` for big-endian `audio/L16`, `rate` a whole
+ * 8000 to 192000 and `channels` 1 or 2 (1 when absent). Undefined for any other type, raw PCM
+ * without a rate or with any other parameter included: Hue plays raw PCM only in a format its
+ * type declares.
+ */
+export function pcmMediaType(mediaType) {
+    if (mediaType.length > 255)
+        return undefined;
+    const endian = pcmEndian.get(mediaType.split(";", 1)[0].trim().toLowerCase());
+    if (!endian)
+        return undefined;
+    const parameters = new Map();
+    const start = mediaType.indexOf(";");
+    if (start !== -1) {
+        pcmParameter.lastIndex = start + 1;
+        for (;;) {
+            const match = pcmParameter.exec(mediaType);
+            if (!match)
+                return undefined;
+            if (match[1] !== undefined) {
+                const name = match[1].toLowerCase();
+                if (parameters.has(name))
+                    return undefined;
+                const value = match[2];
+                parameters.set(name, value.startsWith('"') ? value.slice(1, -1).replace(/\\(.)/g, "$1") : value);
+            }
+            if (match[3] === "")
+                break;
+        }
+    }
+    for (const name of parameters.keys())
+        if (name !== "rate" && name !== "channels")
+            return undefined;
+    const rate = wholeIn(parameters.get("rate"), 8_000, 192_000);
+    const channels = parameters.has("channels") ? wholeIn(parameters.get("channels"), 1, 2) : 1;
+    if (rate === undefined || channels === undefined)
+        return undefined;
+    return `${endian === "big" ? "audio/L16" : "audio/pcm"};rate=${rate};channels=${channels}`;
+}
+/** The media type a `data:` URL's header (between `data:` and its comma) gives its file: raw PCM
+ * whose parameters declare its format as its canonical type (`pcmMediaType`), any other type
+ * without its parameters. Empty when the header names no type. */
+export function headerMediaType(header) {
+    const type = header.split(";", 1)[0].trim();
+    if (!type)
+        return type;
+    const declared = header.endsWith(";base64") ? header.slice(0, -";base64".length) : header;
+    return pcmMediaType(declared) ?? type;
+}
 /** RFC 2397 data without `;base64`: percent-escaped octets, other characters as UTF-8. Undefined
  * when a `%` does not start an escape. */
 function percentDecoded(payload) {
@@ -135,7 +203,7 @@ export function inlineFileBytes(content) {
             ? Buffer.from(payload, "base64")
             : undefined;
     const header = url?.[1];
-    const mediaType = header === undefined ? undefined : header.split(";")[0].trim();
+    const mediaType = header === undefined ? undefined : headerMediaType(header);
     return {
         bytes: decoded ?? Buffer.from(content, "utf8"),
         decoded: decoded !== undefined,
@@ -143,6 +211,8 @@ export function inlineFileBytes(content) {
         ...(decoded !== undefined && !url ? { bareBase64: true } : {}),
     };
 }
+/** OpenAI's `pcm16` audio: raw 16-bit little-endian PCM, 24 kHz mono, as Hue's reader types it. */
+const PCM16 = "audio/pcm;rate=24000;channels=1";
 const audioTypes = {
     wav: "audio/wav",
     mp3: "audio/mpeg",
@@ -152,7 +222,7 @@ const audioTypes = {
     aac: "audio/aac",
     m4a: "audio/mp4",
     webm: "audio/webm",
-    pcm16: "audio/pcm",
+    pcm16: PCM16,
 };
 const documentTypes = {
     pdf: "application/pdf",
@@ -342,16 +412,18 @@ export function contentPath(part, pointer = "") {
 }
 /** A media type as a `data:` URL declares one: `type/subtype`, no parameters. */
 const declaredMediaType = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9!#$&^_.+-]+$/;
-/** The media type a whole string that is a `data:` URL declares, when it declares one: such a
- * string is a file wherever it sits. A web URL, or any other text, is not. */
+/** The media type of a whole string that is a `data:` URL declaring one (`headerMediaType`): such
+ * a string is a file wherever it sits. A web URL, or any other text, is not. */
 function dataUrlType(text) {
     if (!text.startsWith("data:"))
         return undefined;
     const header = dataUrl.exec(text);
     if (!header)
         return undefined;
-    const type = header[1].split(";")[0].trim();
-    return declaredMediaType.test(type) && isMediaContentType(type) ? type : undefined;
+    const type = header[1].split(";", 1)[0].trim();
+    return declaredMediaType.test(type) && isMediaContentType(type)
+        ? headerMediaType(header[1])
+        : undefined;
 }
 /** The modality a media type implies, as Hue's reader names it. */
 export function modalityOf(mediaType) {
@@ -387,7 +459,7 @@ const audioFormats = {
     m4a: "audio/mp4",
     mp4: "audio/mp4",
     webm: "audio/webm",
-    pcm16: "audio/pcm",
+    pcm16: PCM16,
     pcm: "audio/pcm",
 };
 function audioFormatMediaType(format) {
@@ -654,17 +726,27 @@ export function mediaIn(value, source) {
 }
 /**
  * An attribute's recorded text read for files as Hue's reader reads that attribute: JSON by its
- * convention; metadata as JSON when it reads as an object or array, otherwise as the text itself;
- * an OpenLLMetry content as the parts list it encodes (any other content stays text); an
- * OpenInference image URL as the text itself. Undefined for text that reading finds nothing in.
- * Throws for JSON that does not parse or nests too deep.
+ * convention, text that does not parse as the text itself (a Langfuse SDK records a string input
+ * or output as it is, so a whole `data:` URL is a file); metadata as JSON when it reads as an
+ * object or array, otherwise as the text itself; an OpenLLMetry content as the parts list it
+ * encodes (any other content stays text); an OpenInference image URL as the text itself.
+ * Undefined for text that reading finds nothing in. Throws for metadata or parts JSON that does
+ * not parse.
  */
 export function readMediaText(key, text) {
     /** JSON text read as Hue's reader reads it: text it keeps as text holds no file. */
     const json = (parsed) => (readerParses(parsed) ? mediaIn(parsed, text) : undefined);
     switch (readingOf(key)) {
-        case "json":
-            return json(JSON.parse(text));
+        case "json": {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return mediaIn(text);
+            }
+            return json(parsed);
+        }
         case "metadata":
             return /^\s*[[{]/.test(text) ? json(JSON.parse(text)) : mediaIn(text);
         case "parts": {
@@ -729,8 +811,12 @@ export function mediaBytes(file) {
         return { bytes: Buffer.from(file.content, "base64"), decoded: true };
     return inlineFileBytes(file.content);
 }
+/** The type a file is reserved and listed under: the type its part declares, else its `data:`
+ * URL's, raw PCM whose type declares its format in its canonical form (`pcmMediaType`). */
 export function mediaContentType(file, decoded) {
-    return ((isMediaContentType(file.contentType) ? file.contentType : undefined) ??
+    return ((isMediaContentType(file.contentType)
+        ? (pcmMediaType(file.contentType) ?? file.contentType)
+        : undefined) ??
         (isMediaContentType(decoded.urlMediaType) ? decoded.urlMediaType : undefined) ??
         (decoded.decoded ? "application/octet-stream" : "text/plain; charset=utf-8"));
 }

package/dist/large-media.d.ts

@@ -67,7 +67,8 @@ export interface LargeMediaValue extends MediaValue {
  * An attribute's recorded text read for files as `readMediaText` reads it, its long base64 and
  * base64 `data:` URL strings read in place (see {@link skeletonOf}). Undefined for text whose JSON
  * around those strings is over the 8 Mi bound, or that reading finds nothing in. Throws for JSON
- * that does not parse.
+ * that does not parse, except text read by JSON convention that is a `data:` URL, which is read
+ * as the text itself, as `readMediaText` reads it.
  */
 export declare function readLargeMediaText(key: string, text: string, longUnits?: number): Promise<LargeMediaValue | undefined>;
 /**

package/dist/large-media.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { MAX_INLINE_FILE_TEXT, mediaIn, placedMediaText, readerParses, readingOf, } from "./inline-files.js";
+import { headerMediaType, MAX_INLINE_FILE_TEXT, mediaIn, placedMediaText, readerParses, readingOf, } from "./inline-files.js";
 /**
  * Inline media in a value too long for the media inspection bounds (8 Mi UTF-16 code units for one
  * attribute, 16 Mi for a record), read without parsing the files out of it. A span's own attribute
@@ -218,7 +218,8 @@ async function skeletonOf(text, longUnits, held) {
  * An attribute's recorded text read for files as `readMediaText` reads it, its long base64 and
  * base64 `data:` URL strings read in place (see {@link skeletonOf}). Undefined for text whose JSON
  * around those strings is over the 8 Mi bound, or that reading finds nothing in. Throws for JSON
- * that does not parse.
+ * that does not parse, except text read by JSON convention that is a `data:` URL, which is read
+ * as the text itself, as `readMediaText` reads it.
  */
 export async function readLargeMediaText(key, text, longUnits = LONG_STRING_UNITS) {
     const reading = readingOf(key);
@@ -255,7 +256,9 @@ export async function readLargeMediaText(key, text, longUnits = LONG_STRING_UNIT
     };
     switch (reading) {
         case "json":
-            return json();
+            // No JSON text starts with `data:`: such text is the text itself, as `readMediaText` reads
+            // text that does not parse, and a whole `data:` URL is the file.
+            return text.startsWith("data:") ? whole() : json();
         case "metadata":
             return /^\s*[[{]/.test(text) ? json() : whole();
         case "parts":
@@ -408,7 +411,7 @@ export function longFileBytes(file, long) {
             ...(file.base64 ? {} : { bareBase64: true }),
             source,
         };
-    const mediaType = long.header.split(";")[0].trim();
+    const mediaType = headerMediaType(long.header);
     return {
         size: source.size,
         decoded: true,

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.19.0";
+export declare const sdkVersion = "0.20.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.19.0";
+export const sdkVersion = "0.20.0";

package/dist/world/client.d.ts

@@ -0,0 +1,150 @@
+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}. */
+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);
+}
+/** Starts one isolated instance from an immutable World version. */
+export interface CreateInstanceInput extends Omit<CreateRunInput, "environmentVersionId"> {
+    /** Immutable World version to instantiate. */
+    worldVersionId: string;
+}
+/** 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 WorldClient {
+    #private;
+    /** Validated Hue origin. */
+    readonly baseUrl: string;
+    private readonly timeoutMillis;
+    private readonly maxAttempts;
+    constructor(options: EnvironmentClientOptions);
+    /** Compatibility clients override only resource routing. */
+    protected resourcePath(path: string): string;
+    private send;
+    private page;
+    /** Creates an isolated instance from an immutable World version. */
+    createInstance(input: CreateInstanceInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentRun>;
+    /** Reads current or sealed instance state. */
+    getInstance(instanceId: 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;
+    }>;
+    /** Completes or abandons one instance and freezes its evidence. */
+    finishInstance(instanceId: string, input: FinishRunInput): Promise<SealedRun>;
+    /** 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: PublishableWorldDefinition): Promise<EnvironmentVersionSummary>;
+    /** Reads a full immutable environment version and generated action catalog. */
+    getVersion(id: string): Promise<WorldVersion>;
+    /** Creates or recovers one fresh isolated world using a stable idempotency key. */
+    createRun(input: CreateRunInput, options?: {
+        signal?: AbortSignal;
+    }): 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. */
+/** Compatibility client using the original REST resource names. */
+export declare class EnvironmentClient extends WorldClient {
+    /** Publishes the definition shapes supported by the compatibility client. */
+    publishVersion(environmentId: string, definition: PublishableEnvironmentDefinition): Promise<EnvironmentVersionSummary>;
+    /** Reads the definition using the compatibility client's original return type. */
+    getVersion(id: string): Promise<EnvironmentVersion>;
+    protected resourcePath(path: string): string;
+}
+/** Creates the compatibility client using the original REST resource names. */
+export declare function createEnvironmentClient(options: EnvironmentClientOptions): EnvironmentClient;
+/** Connection options for the World API client. */
+export type WorldClientOptions = EnvironmentClientOptions;
+/** Creates a World API client using canonical World and instance routes. */
+export declare function createWorldClient(options: WorldClientOptions): WorldClient;
+export { HueEnvironmentError as HueWorldError, isTransientEnvironmentError as isTransientWorldError, };