@hue-run/sdk 0.9.0 → 0.11.0

package/dist/provider-tools.js

@@ -1,4 +1,5 @@
 import { MAX_CONTENT_BYTES } from "./config.js";
+import { scrubCredentialText } from "./tool-definitions.js";
 const MAX_PROVIDER_ITEMS = 128;
 const MAX_PROVIDER_DEFINITIONS = 512;
 const MAX_PROVIDER_SERVERS = 512;
@@ -19,13 +20,28 @@ function isProviderToolItem(provider, value) {
     return value.type === "mcp_tool_use" || value.type === "server_tool_use";
 }
 function countProviderToolItems(provider, items, start = 0) {
+    let keys;
+    try {
+        keys = Object.keys(items);
+    }
+    catch {
+        // A tail that cannot be listed still holds at least one item nothing could read.
+        return 1;
+    }
     let count = 0;
-    for (const key of Object.keys(items)) {
+    for (const key of keys) {
         const index = Number(key);
         if (!Number.isInteger(index) || index < start || index >= items.length || String(index) !== key)
             continue;
-        if (isProviderToolItem(provider, items[index]))
+        try {
+            if (isProviderToolItem(provider, items[index]))
+                count++;
+        }
+        catch {
+            // A tail item whose `type` cannot be read counts as skipped; the bounded prefix is still
+            // recorded, as the Python SDK does.
             count++;
+        }
     }
     return count;
 }
@@ -41,6 +57,42 @@ function text(value) {
 function errorCode(value) {
     return typeof value === "string" && /^[a-z0-9_]{1,64}$/.test(value) ? value : "error";
 }
+/** The most of a provider's error text scrubbed, and the most exported, in code points. */
+const MAX_ERROR_SCAN = 16_384;
+const MAX_ERROR_TEXT = 1_024;
+/** The first `count` code points of `text`. */
+function codePoints(text, count) {
+    let kept = "";
+    let seen = 0;
+    for (const character of text) {
+        if (seen++ === count)
+            return { text: kept, cut: true };
+        kept += character;
+    }
+    return { text: kept, cut: false };
+}
+/**
+ * A provider's error text as a failed call exports it under content capture: credentials
+ * scrubbed first, then at most 1,024 code points with `…` marking a cut, lone surrogates
+ * replaced and NUL removed. The Python SDK produces the same text.
+ */
+export function providerErrorDescription(value) {
+    const scanned = codePoints(value.toWellFormed().replaceAll("\u0000", ""), MAX_ERROR_SCAN);
+    const bounded = codePoints(scrubCredentialText(scanned.text), MAX_ERROR_TEXT);
+    return bounded.cut || scanned.cut ? `${bounded.text}…` : bounded.text;
+}
+/** An OpenAI MCP call's `error`: its text, or an error object's string `message`. */
+function errorText(value) {
+    let message;
+    try {
+        message = isItem(value) ? value.message : value;
+    }
+    catch {
+        // An error whose message cannot be read still fails its call; only the text is lost.
+        return undefined;
+    }
+    return typeof message === "string" && message.trim() !== "" ? message : undefined;
+}
 /** MCP arguments arrive as a JSON string; record the structure when it parses, else the text. */
 function jsonArguments(value) {
     if (typeof value !== "string")
@@ -59,88 +111,105 @@ function openaiCalls(items, activity) {
     const count = Math.min(items.length, MAX_PROVIDER_ITEMS);
     activity.skipped += countProviderToolItems("openai", items, count);
     for (let index = 0; index < count; index++) {
-        const item = items[index];
-        if (!isItem(item))
-            continue;
-        const callId = text(item.id);
-        switch (item.type) {
-            case "mcp_call": {
-                const name = text(item.name);
-                if (!name) {
-                    activity.skipped++;
-                    break;
-                }
-                activity.calls.push({
-                    name,
-                    callId,
-                    server: text(item.server_label),
-                    arguments: jsonArguments(item.arguments),
-                    ...(item.output !== undefined && item.output !== null ? { result: item.output } : {}),
-                    ...(item.error !== undefined && item.error !== null ? { errorType: "mcp_error" } : {}),
-                });
+        try {
+            openaiItem(items[index], index, activity);
+        }
+        catch {
+            // An item that cannot be read is skipped; the others are still recorded.
+            activity.skipped++;
+        }
+    }
+}
+function openaiItem(item, position, activity) {
+    if (!isItem(item))
+        return;
+    const callId = text(item.id);
+    switch (item.type) {
+        case "mcp_call": {
+            const name = text(item.name);
+            if (!name) {
+                activity.skipped++;
                 break;
             }
-            case "mcp_list_tools": {
-                const server = text(item.server_label);
-                if (!server || !Array.isArray(item.tools)) {
-                    activity.skipped++;
-                    break;
-                }
-                const definitions = [];
-                const definitionCount = Math.min(item.tools.length, MAX_PROVIDER_DEFINITIONS);
-                activity.skipped += item.tools.length - definitionCount;
-                for (let index = 0; index < definitionCount; index++) {
+            const failed = item.error !== undefined && item.error !== null;
+            const detail = failed ? errorText(item.error) : undefined;
+            activity.calls.push({
+                name,
+                callId,
+                position,
+                server: text(item.server_label),
+                arguments: jsonArguments(item.arguments),
+                ...(item.output !== undefined && item.output !== null ? { result: item.output } : {}),
+                ...(failed ? { errorType: "mcp_error" } : {}),
+                ...(detail !== undefined ? { errorText: detail } : {}),
+            });
+            break;
+        }
+        case "mcp_list_tools": {
+            const server = text(item.server_label);
+            if (!server || !Array.isArray(item.tools)) {
+                activity.skipped++;
+                break;
+            }
+            const definitions = [];
+            const definitionCount = Math.min(item.tools.length, MAX_PROVIDER_DEFINITIONS);
+            activity.skipped += item.tools.length - definitionCount;
+            for (let index = 0; index < definitionCount; index++) {
+                try {
                     const tool = item.tools[index];
                     if (!isItem(tool))
                         continue;
+                    // A null field is left out, as absent, so both SDKs digest the same definition.
                     definitions.push({
                         type: "function",
-                        ...(tool.name !== undefined ? { name: tool.name } : {}),
-                        ...(tool.description !== undefined ? { description: tool.description } : {}),
-                        ...(tool.input_schema !== undefined ? { parameters: tool.input_schema } : {}),
-                        ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
+                        ...(tool.name != null ? { name: tool.name } : {}),
+                        ...(tool.description != null ? { description: tool.description } : {}),
+                        ...(tool.input_schema != null ? { parameters: tool.input_schema } : {}),
+                        ...(tool.annotations != null ? { annotations: tool.annotations } : {}),
                     });
                 }
-                activity.listings.push({
-                    server,
-                    definitions,
-                    ...(item.error !== undefined && item.error !== null ? { errorType: "mcp_error" } : {}),
-                });
-                break;
-            }
-            case "web_search_call":
-            case "file_search_call":
-            case "code_interpreter_call": {
-                const name = item.type.slice(0, -"_call".length);
-                const failed = item.status === "failed" ? { errorType: "failed" } : {};
-                if (item.type === "web_search_call")
-                    activity.calls.push({ name, callId, arguments: item.action, ...failed });
-                else if (item.type === "file_search_call")
-                    activity.calls.push({
-                        name,
-                        callId,
-                        arguments: { queries: item.queries },
-                        ...(item.results !== undefined && item.results !== null
-                            ? { result: item.results }
-                            : {}),
-                        ...failed,
-                    });
-                else
-                    activity.calls.push({
-                        name,
-                        callId,
-                        arguments: { code: item.code, container_id: item.container_id },
-                        ...(item.outputs !== undefined && item.outputs !== null
-                            ? { result: item.outputs }
-                            : {}),
-                        ...failed,
-                    });
-                break;
+                catch {
+                    // A definition that cannot be read is skipped; the rest of the listing is kept.
+                    activity.skipped++;
+                }
             }
-            default:
-                // Messages, reasoning, approval requests and other items are not executed tools.
-                break;
+            activity.listings.push({
+                server,
+                definitions,
+                ...(item.error !== undefined && item.error !== null ? { errorType: "mcp_error" } : {}),
+            });
+            break;
         }
+        case "web_search_call":
+        case "file_search_call":
+        case "code_interpreter_call": {
+            const name = item.type.slice(0, -"_call".length);
+            const failed = item.status === "failed" ? { errorType: "failed" } : {};
+            if (item.type === "web_search_call")
+                activity.calls.push({ name, callId, position, arguments: item.action, ...failed });
+            else if (item.type === "file_search_call")
+                activity.calls.push({
+                    name,
+                    callId,
+                    position,
+                    arguments: { queries: item.queries },
+                    ...(item.results !== undefined && item.results !== null ? { result: item.results } : {}),
+                    ...failed,
+                });
+            else
+                activity.calls.push({
+                    name,
+                    callId,
+                    position,
+                    arguments: { code: item.code, container_id: item.container_id },
+                    ...(item.outputs !== undefined && item.outputs !== null ? { result: item.outputs } : {}),
+                    ...failed,
+                });
+            break;
+        }
+        default:
+            // Messages, reasoning, approval requests and other items are not executed tools.
+            break;
     }
 }
 /** Anthropic Messages `content` blocks: a use block paired with the result block that names it. */
@@ -149,47 +218,64 @@ function anthropicCalls(blocks, activity) {
     const count = Math.min(blocks.length, MAX_PROVIDER_ITEMS);
     const truncated = blocks.length > MAX_PROVIDER_ITEMS;
     activity.skipped += countProviderToolItems("anthropic", blocks, count);
+    // Each block is read once; one that cannot be read is skipped and the rest still recorded.
+    const readable = [];
     for (let index = 0; index < count; index++) {
-        const block = blocks[index];
-        if (isItem(block) &&
-            typeof block.type === "string" &&
-            block.type.endsWith("_tool_result") &&
-            typeof block.tool_use_id === "string")
-            results.set(block.tool_use_id, block);
+        try {
+            const block = blocks[index];
+            if (isItem(block) &&
+                typeof block.type === "string" &&
+                block.type.endsWith("_tool_result") &&
+                typeof block.tool_use_id === "string")
+                results.set(block.tool_use_id, block);
+            readable.push(block);
+        }
+        catch {
+            activity.skipped++;
+            readable.push(undefined);
+        }
     }
     for (let index = 0; index < count; index++) {
-        const block = blocks[index];
-        if (!isItem(block) || (block.type !== "mcp_tool_use" && block.type !== "server_tool_use"))
-            continue;
-        const name = text(block.name);
-        const callId = text(block.id);
-        if (!name) {
-            activity.skipped++;
-            continue;
+        try {
+            anthropicBlock(readable[index], index, results, truncated, activity);
         }
-        const result = callId === undefined ? undefined : results.get(callId);
-        // When the response was truncated, an unmatched use block may have its result outside the
-        // bounded prefix. Do not export it as a successful call with a missing result.
-        if (truncated && result === undefined) {
+        catch {
             activity.skipped++;
-            continue;
         }
-        const content = result?.content;
-        let errorType;
-        if (result?.is_error === true)
-            errorType = "mcp_error";
-        else if (isItem(content) && typeof content.type === "string" && content.type.endsWith("_error"))
-            errorType = errorCode(content.error_code);
-        activity.calls.push({
-            name,
-            callId,
-            ...(block.type === "mcp_tool_use" ? { server: text(block.server_name) } : {}),
-            arguments: block.input,
-            ...(content !== undefined ? { result: content } : {}),
-            ...(errorType ? { errorType } : {}),
-        });
     }
 }
+function anthropicBlock(block, position, results, truncated, activity) {
+    if (!isItem(block) || (block.type !== "mcp_tool_use" && block.type !== "server_tool_use"))
+        return;
+    const name = text(block.name);
+    const callId = text(block.id);
+    if (!name) {
+        activity.skipped++;
+        return;
+    }
+    const result = callId === undefined ? undefined : results.get(callId);
+    // When the response was truncated, an unmatched use block may have its result outside the
+    // bounded prefix. Do not export it as a successful call with a missing result.
+    if (truncated && result === undefined) {
+        activity.skipped++;
+        return;
+    }
+    const content = result?.content;
+    let errorType;
+    if (result?.is_error === true)
+        errorType = "mcp_error";
+    else if (isItem(content) && typeof content.type === "string" && content.type.endsWith("_error"))
+        errorType = errorCode(content.error_code);
+    activity.calls.push({
+        name,
+        callId,
+        position,
+        ...(block.type === "mcp_tool_use" ? { server: text(block.server_name) } : {}),
+        arguments: block.input,
+        ...(content !== undefined ? { result: content } : {}),
+        ...(errorType ? { errorType } : {}),
+    });
+}
 /**
  * Reads the hosted tool calls out of a provider response: the `output` items of an OpenAI
  * Responses API response, or the `content` blocks of an Anthropic Messages API response. An array

package/dist/safety.d.ts

@@ -1,7 +1,13 @@
 import { type Span } from "@opentelemetry/api";
 export declare function noopSpan(): Span;
 export declare function safeSpan(source: Span, failed: () => void): Span;
+/** The bounds `encodeContent` enforces while it copies a value. */
+export interface EncodeLimits {
+    bytes: number;
+    nodes: number;
+    depth: number;
+}
 /** Validate a bounded data tree without invoking toJSON or property getters. */
-export declare function encodeContent(value: unknown): string;
+export declare function encodeContent(value: unknown, limits?: EncodeLimits): string;
 /** Bounded conservative accounting for the record data retained by our queue, not total process RSS. */
 export declare function estimateRecordBytes(value: unknown, limit: number): number;

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/snapshot.d.ts

@@ -1,11 +1,11 @@
 import type { ReadableSpan } from "@opentelemetry/sdk-trace";
 import type { ReadableLogRecord, ReadWriteLogRecord } from "@opentelemetry/sdk-logs";
-export declare function snapshotSpan(source: ReadableSpan, limit: number): {
+export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean): {
     record: ReadableSpan;
     bytes: number;
     unresolvedResource: boolean;
 };
-export declare function snapshotLog(source: ReadableLogRecord, limit: number): {
+export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean): {
     record: ReadWriteLogRecord;
     bytes: number;
     unresolvedResource: boolean;