@hue-run/sdk 0.9.0 → 0.11.0

package/dist/snapshot.js

@@ -1,6 +1,7 @@
 import { createTraceState } from "@opentelemetry/api";
 import { types as utilTypes } from "node:util";
 import { resourceFromAttributes } from "@opentelemetry/resources";
+import { hashInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, isMessageKey, } from "./inline-files.js";
 // Intrinsic accessors are captured once and invoked with an explicit receiver so a
 // hostile object cannot override them; the unbound reference is the point.
 // eslint-disable-next-line @typescript-eslint/unbound-method
@@ -10,20 +11,52 @@ const typedArraySet = Uint8Array.prototype.set;
 /** Copies only exported data, with the same finite budget used for admission. */
 class Snapshot {
     limit;
+    captureContent;
     bytes = 512;
     unresolvedResource = false;
     nodes = 0;
     ancestors = new Set();
     copied = new Map();
-    constructor(limit) {
+    hashed = new Map();
+    inspected = 0;
+    /** In metadata-only mode the recorded messages, which export strips, are not copied at all. */
+    constructor(limit, captureContent = true) {
         this.limit = limit;
+        this.captureContent = captureContent;
     }
     charge(bytes) {
         this.bytes += bytes;
         if (this.bytes > this.limit)
             throw new RangeError("Telemetry byte budget exceeded");
     }
-    copy(value, depth = 0) {
+    /**
+     * An attribute map. A large inline file in a message attribute shrinks to its digest before it
+     * is charged: export replaces it anyway, and charging the file could drop the whole record.
+     */
+    attributes(value) {
+        return this.copy(value, 1, "attributes");
+    }
+    /** A message attribute with its large inline files hashed. The same text is hashed once per
+     * record, and a record inspects at most {@link INLINE_FILE_TEXT_PER_RECORD} of it in all;
+     * beyond that, messages are charged as recorded. */
+    inlineFiles(key, value) {
+        // A UTF-16 unit is at most three UTF-8 bytes, so shorter text cannot hold a file to hash.
+        if (typeof value !== "string" || !isMessageKey(key) || value.length * 3 <= INLINE_FILE_LIMIT)
+            return value;
+        if (this.hashed.has(value))
+            return this.hashed.get(value);
+        if (this.inspected + value.length > INLINE_FILE_TEXT_PER_RECORD)
+            return value;
+        this.inspected += value.length;
+        const result = hashInlineFiles(key, value);
+        this.hashed.set(value, result);
+        return result;
+    }
+    /** Span events, whose attributes are attribute maps. */
+    events(value) {
+        return this.copy(value, 1, "events");
+    }
+    copy(value, depth = 0, shape = "value") {
         if (++this.nodes > 16384 || depth > 32)
             throw new RangeError("Telemetry complexity limit exceeded");
         this.charge(16);
@@ -69,7 +102,7 @@ class Snapshot {
                 const descriptor = Object.getOwnPropertyDescriptor(value, index);
                 if (descriptor && !("value" in descriptor))
                     throw new TypeError("Telemetry accessors are unsupported");
-                copy.push(this.copy(descriptor?.value, depth + 1));
+                copy.push(this.copy(descriptor?.value, depth + 1, shape === "events" ? "event" : "value"));
             }
         }
         else {
@@ -79,8 +112,10 @@ class Snapshot {
                 const descriptor = Object.getOwnPropertyDescriptor(value, key);
                 if (!descriptor || !("value" in descriptor))
                     throw new TypeError("Telemetry accessors are unsupported");
+                if (shape === "attributes" && !this.captureContent && isMessageKey(key))
+                    continue;
                 this.charge(key.length * 2 + 16);
-                copy[key] = this.copy(descriptor.value, depth + 1);
+                copy[key] = this.copy(shape === "attributes" ? this.inlineFiles(key, descriptor.value) : descriptor.value, depth + 1, shape === "event" && key === "attributes" ? "attributes" : "value");
             }
         }
         this.ancestors.delete(value);
@@ -126,14 +161,14 @@ class Snapshot {
 function contextReader(context) {
     return () => context;
 }
-export function snapshotSpan(source, limit) {
-    const snapshot = new Snapshot(limit);
+export function snapshotSpan(source, limit, captureContent = true) {
+    const snapshot = new Snapshot(limit, captureContent);
     const context = snapshot.context(source.spanContext());
     if (source.links.length > 16384)
         throw new RangeError("Link complexity limit exceeded");
     const links = source.links.map((link) => ({
         context: snapshot.context(link.context),
-        attributes: snapshot.copy(link.attributes),
+        attributes: snapshot.attributes(link.attributes),
         droppedAttributesCount: snapshot.copy(link.droppedAttributesCount),
     }));
     const record = {
@@ -145,13 +180,13 @@ export function snapshotSpan(source, limit) {
             duration: source.duration,
             ended: source.ended,
             status: source.status,
-            attributes: source.attributes,
-            events: source.events,
             instrumentationScope: source.instrumentationScope,
             droppedAttributesCount: source.droppedAttributesCount,
             droppedEventsCount: source.droppedEventsCount,
             droppedLinksCount: source.droppedLinksCount,
         }),
+        attributes: snapshot.attributes(source.attributes),
+        events: snapshot.events(source.events),
         spanContext: contextReader(context),
         parentSpanContext: snapshot.context(source.parentSpanContext),
         links,
@@ -159,8 +194,8 @@ export function snapshotSpan(source, limit) {
     };
     return { record, bytes: snapshot.bytes, unresolvedResource: snapshot.unresolvedResource };
 }
-export function snapshotLog(source, limit) {
-    const snapshot = new Snapshot(limit);
+export function snapshotLog(source, limit, captureContent = true) {
+    const snapshot = new Snapshot(limit, captureContent);
     // Only our batching processor sees this copy. Its writer methods deliberately
     // cannot mutate the admitted snapshot or invalidate its charged byte count.
     const record = {
@@ -171,10 +206,10 @@ export function snapshotLog(source, limit) {
             severityNumber: source.severityNumber,
             eventName: source.eventName,
             body: source.body,
-            attributes: source.attributes,
             instrumentationScope: source.instrumentationScope,
             droppedAttributesCount: source.droppedAttributesCount,
         }),
+        attributes: snapshot.attributes(source.attributes),
         spanContext: snapshot.context(source.spanContext),
         resource: snapshot.resource(source.resource),
         setAttribute() {

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/transport.js

@@ -191,8 +191,8 @@ export class HueTransport {
             const remaining = (advisory ? this.options.maxQueueBytes / 4 : this.options.maxQueueBytes) -
                 this.pendingBytes;
             const snapshot = signal === "traces"
-                ? snapshotSpan(record, remaining)
-                : snapshotLog(record, remaining);
+                ? snapshotSpan(record, remaining, this.options.captureContent)
+                : snapshotLog(record, remaining, this.options.captureContent);
             this.pendingBytes += snapshot.bytes;
             if (signal === "traces")
                 this.spans.set(snapshot.record, snapshot.bytes);

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.9.0";
+export declare const sdkVersion = "0.11.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.9.0";
+export const sdkVersion = "0.11.0";

package/package.json

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