@hue-run/sdk 0.10.0 → 0.11.1

package/dist/safety.js

@@ -89,21 +89,23 @@ class SafeSpan {
 export function safeSpan(source, failed) {
     return new SafeSpan(source, failed);
 }
+/** One content attribute's bounds. */
+const contentLimits = { bytes: MAX_CONTENT_BYTES, nodes: 16384, depth: 32 };
 /** Validate a bounded data tree without invoking toJSON or property getters. */
-export function encodeContent(value) {
+export function encodeContent(value, limits = contentLimits) {
     let nodes = 0;
     let bytes = 0;
     const ancestors = new Set();
     const charge = (amount) => {
         bytes += amount;
-        if (bytes > MAX_CONTENT_BYTES)
+        if (bytes > limits.bytes)
             throw new RangeError("Content limit exceeded");
     };
     const visit = (item, depth) => {
-        if (++nodes > 16384 || depth > 32)
+        if (++nodes > limits.nodes || depth > limits.depth)
             throw new RangeError("Content complexity limit exceeded");
         if (typeof item === "string") {
-            if (item.length > MAX_CONTENT_BYTES)
+            if (item.length > limits.bytes)
                 throw new RangeError("Content limit exceeded");
             charge(Buffer.byteLength(JSON.stringify(item)));
             return item;
@@ -128,9 +130,9 @@ export function encodeContent(value) {
         const result = array ? [] : Object.create(null);
         // Own descriptors avoid executing application accessors during capture.
         const keys = array
-            ? Array.from({ length: Math.min(item.length, 16385) }, (_, i) => String(i))
+            ? Array.from({ length: Math.min(item.length, limits.nodes + 1) }, (_, i) => String(i))
             : Object.keys(item);
-        if (keys.length > 16384)
+        if (keys.length > limits.nodes)
             throw new RangeError("Content complexity limit exceeded");
         for (const key of keys) {
             const descriptor = Object.getOwnPropertyDescriptor(item, key);
@@ -147,7 +149,7 @@ export function encodeContent(value) {
         return result;
     };
     const encoded = JSON.stringify(visit(value, 0));
-    if (Buffer.byteLength(encoded) > MAX_CONTENT_BYTES)
+    if (Buffer.byteLength(encoded) > limits.bytes)
         throw new RangeError("Content limit exceeded");
     return encoded;
 }

package/dist/setup/cli.js

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { FileSetupCheckpointAdapter, setupRunId } from "./checkpoint.js";
 import { SetupBackendAdapter } from "./backend.js";
 import { detectSetupProject } from "./detect.js";
+import { loadCommand, MissingPeerError } from "./peers.js";
 import { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, } from "./render.js";
 import { runSetup } from "./runner.js";
 import { SETUP_EVENT_CONTRACT_VERSION } from "./types.js";
@@ -11,9 +12,22 @@ const commands = new Set(["setup", "resume", "status", "claim"]);
 // Additional commands live in ../cli and load lazily so the setup parser, its usage text and its
 // JSONL error contract stay untouched for every other input. Add a command with one entry.
 const extensions = new Map([
-    ["eval", async () => (await import("../cli/eval.js")).runEvalCommand(process.argv.slice(3))],
-    ["login", async () => (await import("../cli/login.js")).runLoginCommand(process.argv.slice(3))],
-    ["mcp", async () => (await import("../cli/mcp.js")).runMcpCommand(process.argv.slice(3))],
+    [
+        "eval",
+        async () => (await loadCommand("eval", () => import("../cli/eval.js"))).runEvalCommand(process.argv.slice(3)),
+    ],
+    [
+        "login",
+        async () => (await loadCommand("login", () => import("../cli/login.js"))).runLoginCommand(process.argv.slice(3)),
+    ],
+    [
+        "mcp",
+        async () => (await loadCommand("mcp", () => import("../cli/mcp.js"))).runMcpCommand(process.argv.slice(3)),
+    ],
+    [
+        "listen",
+        async () => (await loadCommand("listen", () => import("../cli/listen.js"))).runListenCommand(process.argv.slice(3)),
+    ],
 ]);
 function writeEvent(event, mode, width) {
     const line = mode === "jsonl"
@@ -26,8 +40,17 @@ function writeEvent(event, mode, width) {
 }
 async function main() {
     const extension = extensions.get(process.argv[2] ?? "");
-    if (extension)
-        return extension();
+    if (extension) {
+        try {
+            return await extension();
+        }
+        catch (error) {
+            if (!(error instanceof MissingPeerError))
+                throw error;
+            process.stderr.write(`${error.message}\n`);
+            return 2;
+        }
+    }
     const agentRequested = process.argv.slice(2).includes("--agent");
     let parsed;
     try {
@@ -47,7 +70,7 @@ async function main() {
     }
     catch {
         if (!agentRequested) {
-            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
+            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
             return 2;
         }
         const event = {
@@ -78,7 +101,7 @@ async function main() {
             process.stdout.write(`${renderJsonlEvent(event)}\n`);
             return 2;
         }
-        process.stdout.write("Usage: hue <setup|resume|status|claim|login|eval|mcp> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
+        process.stdout.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
         return 0;
     }
     const command = parsed.positionals[0];
@@ -110,7 +133,7 @@ async function main() {
             process.stdout.write(`${renderJsonlEvent(event)}\n`);
         }
         else
-            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
+            process.stderr.write("Usage: hue <setup|resume|status|claim|login|eval|mcp|listen> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
         return 2;
     }
     const mode = selectSetupOutputMode({

package/dist/setup/peers.d.ts

@@ -0,0 +1,13 @@
+/** A peer dependency of `@hue-run/sdk` that a command needs and the project has not installed. */
+export declare class MissingPeerError extends Error {
+    readonly command: string;
+    readonly peer: string;
+    readonly range: string;
+    constructor(command: string, peer: string, range: string);
+}
+/**
+ * Loads a command module. When the import fails because one of the SDK's peers, such as `zod` or
+ * `@opentelemetry/api`, is not installed, the failure names that peer and how to add it instead
+ * of the runtime's resolution error; any other failure is rethrown unchanged.
+ */
+export declare function loadCommand<T>(command: string, load: () => Promise<T>): Promise<T>;

package/dist/setup/peers.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+/** A peer dependency of `@hue-run/sdk` that a command needs and the project has not installed. */
+export class MissingPeerError extends Error {
+    command;
+    peer;
+    range;
+    constructor(command, peer, range) {
+        super(`hue ${command} needs ${peer}, a peer dependency of @hue-run/sdk that this project has not installed. Install it with: npm install "${peer}@${range}" (or bun add, pnpm add or yarn add with the same argument)`);
+        this.command = command;
+        this.peer = peer;
+        this.range = range;
+        this.name = "MissingPeerError";
+    }
+}
+/** The range `@hue-run/sdk` declares for a peer, or undefined when `name` is not one of its peers. */
+function peerRange(name) {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+        const range = manifest.peerDependencies?.[name];
+        return typeof range === "string" ? range : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Loads a command module. When the import fails because one of the SDK's peers, such as `zod` or
+ * `@opentelemetry/api`, is not installed, the failure names that peer and how to add it instead
+ * of the runtime's resolution error; any other failure is rethrown unchanged.
+ */
+export async function loadCommand(command, load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        // Only a package that cannot be found at all; "Cannot find module" for a file or subpath of
+        // an installed package is another failure and keeps its own message.
+        const missing = /Cannot find package ['"]((?:@[^/'"]+\/)?[^/'"]+)['"]/.exec(error instanceof Error ? error.message : "")?.[1];
+        const range = missing === undefined ? undefined : peerRange(missing);
+        if (missing === undefined || range === undefined)
+            throw error;
+        throw new MissingPeerError(command, missing, range);
+    }
+}

package/dist/tool-definitions.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Removes credentials from free text a provider returned, such as an MCP call's error message,
+ * with the rules tool definitions use, extended for text: each `http`, `https`, `ws`, `wss` or
+ * `ftp` URL loses its userinfo and fragment and every query value becomes `[redacted]`, as a
+ * `url` field does (an unparseable one becomes `[redacted]`), and a URL with any other scheme
+ * becomes `[redacted]` when it has an `@`, `?` or `#`; a token with a known credential prefix
+ * (`hue_sk_`, `sk-`, `xoxb-`, `ya29.` and others), the credential after an authorization scheme
+ * (`Bearer`, `Basic`, `Token`), the whole value of an `Authorization` header, and the value of a
+ * `key=value` or `key: value` pair whose key names a credential (quoted, escaped-quoted or bare)
+ * become `[redacted]`.
+ */
+export declare function scrubCredentialText(text: string): string;
 /**
  * Removes hosted-tool credentials from an exported attribute value, before the caller's `redact`.
  * Tool definitions come from OpenTelemetry GenAI (`gen_ai.tool.definitions`), AI SDK 6
@@ -18,3 +30,9 @@ export declare function scrubToolCredentials(key: string, value: unknown): unkno
  * already sets are kept.
  */
 export declare function withToolCatalogSummary<T extends Record<string, unknown>>(source: T): T;
+/**
+ * The metadata-only summary of one JSON-encoded definition list: `hue.tool.names` and
+ * `hue.tool.definitions.sha256`, exactly as export summarizes a record's
+ * `gen_ai.tool.definitions`. Empty when the list cannot be summarized.
+ */
+export declare function toolCatalogSummary(definitions: string): Record<string, string | string[]>;

package/dist/tool-definitions.js

@@ -72,6 +72,223 @@ function isCredentialKey(key) {
         normalized.endsWith("apikey") ||
         normalized.endsWith("credential"));
 }
+/** A URL's `://` and everything after it up to whitespace, a quote or `<>`. A quoted value right
+ * after `=` (`?token="…"`) is part of the URL, so the whole value is replaced. */
+const urlRest = /:\/\/(?:[^\s"'<>`]|(?<==)"[^"<>`\r\n]*"|(?<==)'[^'<>`\r\n]*'|(?<==)["'])+/y;
+const isSchemeLetter = (code) => (code | 0x20) >= 0x61 && (code | 0x20) <= 0x7a;
+/** `a-z`, `0-9`, `+`, `.` and `-`, case-insensitively. */
+const isSchemeCharacter = (code) => isSchemeLetter(code) ||
+    (code >= 0x30 && code <= 0x39) ||
+    code === 0x2b ||
+    code === 0x2e ||
+    code === 0x2d;
+/** Scrubs each URL in free text. Each `://` is found by search and its scheme read back from it:
+ * up to 64 scheme characters, starting at a letter, so a longer run before `://` still leaves a
+ * URL to scrub and a long run such as `a.a.a…` costs one pass. */
+function scrubTextUrls(text, state) {
+    let result = "";
+    let copied = 0;
+    for (let index = text.indexOf("://"); index !== -1; index = text.indexOf("://", index + 1)) {
+        if (index < copied)
+            continue;
+        let start = index;
+        while (start > copied && index - start < 64 && isSchemeCharacter(text.charCodeAt(start - 1)))
+            start--;
+        while (start < index && !isSchemeLetter(text.charCodeAt(start)))
+            start++;
+        if (start === index)
+            continue;
+        urlRest.lastIndex = index;
+        const rest = urlRest.exec(text);
+        if (!rest)
+            continue;
+        const end = index + rest[0].length;
+        result += text.slice(copied, start) + scrubTextUrl(text.slice(start, end), state);
+        copied = end;
+    }
+    return result + text.slice(copied);
+}
+/** Schemes WHATWG parses as hierarchical, which both SDKs serialize alike. */
+const specialScheme = /^(?:https?|wss?|ftp):/i;
+/** A URL in free text. One with another scheme, which runtimes parse differently, is replaced
+ * whole when it could carry userinfo, a query or a fragment. */
+function scrubTextUrl(url, state) {
+    if (specialScheme.test(url))
+        return scrubUrl(url, state);
+    return /[@?#]/.test(url) ? REDACTED : url;
+}
+/** A credential its own prefix identifies wherever it appears, `%` escapes included: Hue's API, MCP,
+ * world, attempt, simulation, setup, install and invocation tokens, and OpenAI and Anthropic
+ * (`sk-`), Stripe, Slack, Google OAuth, GitHub and GitLab ones. */
+const prefixedToken = /\b(?:hue_(?:sk|mcp|world|attempt|sim|setup|install|inv)_|sk-|[rs]k_(?:live|test)_|xox[abcdoprs]-|xapp-|ya29\.|gh[opsur]_|github_pat_|glpat-)[a-z0-9_.~+/=%-]{8,}/gi;
+/** An authorization scheme followed by its credential, as in an `Authorization` header, up to
+ * whitespace, a quote, a delimiter or a backslash. The credential cannot start with `=` or `:`, so
+ * `token = value` and `Token : value` are left to the key-value rule. */
+const authorizationValue = /\b(bearer|basic|token)(\s+)[^\s"'`<>=:,;(){}[\]\\][^\s"'`<>,;(){}[\]\\]*/gi;
+/** The key and separator of a `key=value` or `key: value` pair, the key optionally quoted, with a
+ * backslash-escaped quote too (JSON inside a string). A key starts where no key character precedes
+ * it, so each word is tried once and a long run stays linear. The value is not consumed, so a pair
+ * inside another pair's value (`error: token=…`) is found. */
+const pairKey = /(\\?["']|)(?<![a-z0-9_-])([a-z0-9_-]+)\1(\s*[:=]\s*)/gi;
+/** A quoted value to its closing quote on the same line, spaces and escaped quotes included, or
+ * one between backslash-escaped quotes, double or single. */
+const quotedValue = /"(?:[^"\\\r\n]|\\[^\r\n])+"|'(?:[^'\\\r\n]|\\[^\r\n])+'|\\"(?:[^"\\\r\n]|\\[^"\r\n])+\\"|\\'(?:[^'\\\r\n]|\\[^'\r\n])+\\'/y;
+/** An unquoted value, or one whose quote does not close on its line, up to whitespace, a quote or
+ * a delimiter; a value already replaced, or a scheme whose credential was, is left alone. */
+const bareValue = /(\\?["']?)(?!\[redacted\]|%5Bredacted%5D|(?:bearer|basic|token)\s)[^\s"',;&})\]]+/iy;
+/** An `Authorization` header's unquoted value: its scheme and the credential after it (`Bot …`,
+ * `OAuth1 …`), or a lone credential. One already replaced is left alone. */
+const authorizationBare = /(\\?["']?)(?!\[redacted\]|%5Bredacted%5D)([^\s"',;})\]]+)(?:[ \t]+(?:\[redacted\]|[^\s"',;})\]]+))?/y;
+function normalizedKey(key) {
+    return key.toLowerCase().replace(/[-_]/g, "");
+}
+/** A key naming a credential in free text: a tool definition's credential keys, any header ending
+ * in `Authorization`, and `Bearer` and `Basic`. */
+function isTextCredentialKey(key) {
+    const normalized = normalizedKey(key);
+    return (isCredentialKey(key) ||
+        normalized.endsWith("authorization") ||
+        normalized === "bearer" ||
+        normalized === "basic");
+}
+/** `API key: …`: a credential named in two words, `key` right after `API`. */
+const apiBefore = /(?:^|[^a-z0-9_])api[ \t]+$/i;
+function isApiKeyPhrase(text, keyStart, key) {
+    return (key.toLowerCase() === "key" && apiBefore.test(text.slice(Math.max(0, keyStart - 16), keyStart)));
+}
+/** Whether a quote, or a backslash-escaped quote, opens at `index`. */
+function opensQuote(text, index) {
+    const character = text[index];
+    return (character === '"' ||
+        character === "'" ||
+        text.startsWith('\\"', index) ||
+        text.startsWith("\\'", index));
+}
+/** The value of each pair whose key names a credential, without its quotes. A pair inside an
+ * earlier pair's value is kept when its value runs past that value. */
+function pairSpans(text) {
+    const spans = [];
+    let covered = 0;
+    // The last `Authorization` value read: where it starts, where its first word ends and where it
+    // ends. A value starting inside that first word ends where it does, so each run is read once.
+    let authorization;
+    for (const match of text.matchAll(pairKey)) {
+        const start = match.index + match[0].length;
+        const key = match[2];
+        const keyStart = match.index + match[1].length;
+        if (!(isTextCredentialKey(key) || isApiKeyPhrase(text, keyStart, key)))
+            continue;
+        const nested = start < covered;
+        const isAuthorization = normalizedKey(key).endsWith("authorization");
+        // A value inside an earlier value ends where that value's run or quote ends, so it can run
+        // past it only by opening a quote (which may be the one that closes the earlier value) or,
+        // for `Authorization`, by the word after its scheme.
+        if (nested && !isAuthorization && !opensQuote(text, start))
+            continue;
+        quotedValue.lastIndex = start;
+        const quoted = quotedValue.exec(text);
+        let open;
+        let end;
+        if (quoted) {
+            open = quoted[0].startsWith("\\") ? 2 : 1;
+            end = start + quoted[0].length;
+        }
+        else if (isAuthorization) {
+            if (authorization &&
+                start > authorization.from &&
+                start < authorization.firstEnd &&
+                !opensQuote(text, start) &&
+                !text.startsWith("[redacted]", start) &&
+                !text.startsWith("%5Bredacted%5D", start)) {
+                open = 0;
+                end = authorization.end;
+            }
+            else {
+                authorizationBare.lastIndex = start;
+                const value = authorizationBare.exec(text);
+                if (!value)
+                    continue;
+                open = value[1].length;
+                end = start + value[0].length;
+                authorization = { from: start, firstEnd: start + open + value[2].length, end };
+            }
+        }
+        else {
+            bareValue.lastIndex = start;
+            const value = bareValue.exec(text);
+            if (!value)
+                continue;
+            open = value[1].length;
+            end = start + value[0].length;
+        }
+        if (end <= covered)
+            continue;
+        spans.push([start + open, end - (quoted ? open : 0)]);
+        covered = end;
+    }
+    return spans;
+}
+/** The credential after each authorization scheme. A scheme word can end an earlier credential
+ * (`…~bearer SECRET`), so the search resumes at each credential, which is read at most once more. */
+function authorizationSpans(text) {
+    const spans = [];
+    authorizationValue.lastIndex = 0;
+    for (let match = authorizationValue.exec(text); match; match = authorizationValue.exec(text)) {
+        const credential = match.index + match[1].length + match[2].length;
+        spans.push([credential, match.index + match[0].length]);
+        authorizationValue.lastIndex = credential;
+    }
+    return spans;
+}
+/** Each match of a global pattern. */
+function matchSpans(text, pattern) {
+    return [...text.matchAll(pattern)].map((match) => [match.index, match.index + match[0].length]);
+}
+/** Replaces the union of the spans with `[redacted]`, each run of overlapping or touching spans
+ * once. */
+function redactSpans(text, spans) {
+    spans.sort(([a, b], [c, d]) => a - c || b - d);
+    let result = "";
+    let copied = 0;
+    let run;
+    const flush = () => {
+        if (!run)
+            return;
+        result += `${text.slice(copied, run[0])}${REDACTED}`;
+        copied = run[1];
+    };
+    for (const [start, end] of spans) {
+        if (run && start <= run[1])
+            run[1] = Math.max(run[1], end);
+        else {
+            flush();
+            run = [start, end];
+        }
+    }
+    flush();
+    return result + text.slice(copied);
+}
+/**
+ * Removes credentials from free text a provider returned, such as an MCP call's error message,
+ * with the rules tool definitions use, extended for text: each `http`, `https`, `ws`, `wss` or
+ * `ftp` URL loses its userinfo and fragment and every query value becomes `[redacted]`, as a
+ * `url` field does (an unparseable one becomes `[redacted]`), and a URL with any other scheme
+ * becomes `[redacted]` when it has an `@`, `?` or `#`; a token with a known credential prefix
+ * (`hue_sk_`, `sk-`, `xoxb-`, `ya29.` and others), the credential after an authorization scheme
+ * (`Bearer`, `Basic`, `Token`), the whole value of an `Authorization` header, and the value of a
+ * `key=value` or `key: value` pair whose key names a credential (quoted, escaped-quoted or bare)
+ * become `[redacted]`.
+ */
+export function scrubCredentialText(text) {
+    const scrubbed = scrubTextUrls(text, { changed: false });
+    // Every rule reads the same text and their matches are replaced together, so no rule's
+    // replacement can hide text another rule would have matched.
+    return redactSpans(scrubbed, [
+        ...pairSpans(scrubbed),
+        ...matchSpans(scrubbed, prefixedToken),
+        ...authorizationSpans(scrubbed),
+    ]);
+}
 /** OpenInference records each tool as `llm.tools.{index}.tool.json_schema`. */
 const openInferenceTool = /^llm\.tools\.(\d+)\.tool\.json_schema$/;
 /**
@@ -272,3 +489,18 @@ export function withToolCatalogSummary(source) {
     }
     return { ...summary, ...source };
 }
+/**
+ * The metadata-only summary of one JSON-encoded definition list: `hue.tool.names` and
+ * `hue.tool.definitions.sha256`, exactly as export summarizes a record's
+ * `gen_ai.tool.definitions`. Empty when the list cannot be summarized.
+ */
+export function toolCatalogSummary(definitions) {
+    const summarized = withToolCatalogSummary({
+        "gen_ai.tool.definitions": definitions,
+    });
+    const summary = {};
+    for (const key of ["hue.tool.names", "hue.tool.definitions.sha256"])
+        if (key in summarized)
+            summary[key] = summarized[key];
+    return summary;
+}

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.10.0";
+export declare const sdkVersion = "0.11.1";

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.10.0";
+export const sdkVersion = "0.11.1";

package/package.json

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