@hue-run/sdk 0.23.0 → 0.23.1

package/CLI.md

@@ -42,7 +42,7 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.23.0`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.23.1`, `@opentelemetry/api@1.9.1` and
 `@opentelemetry/context-async-hooks@2.11.0`; Python setup uses its separately tested package pin.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
@@ -381,8 +381,8 @@ and Hue never receives or stores them. The command is part of the `hue` executab
 #   LANGFUSE_PUBLIC_KEY=pk-lf-...
 #   LANGFUSE_SECRET_KEY=sk-lf-...
 #   LANGFUSE_BASE_URL=https://cloud.langfuse.com
-npx -y @hue-run/sdk@0.23.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.23.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` come from the environment or `--env-path`
@@ -892,7 +892,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.23.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.23.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -903,7 +903,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.23.0.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.23.1.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -945,10 +945,10 @@ otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`
 production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx -y @hue-run/sdk@0.23.0 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.23.0 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
-npx -y @hue-run/sdk@0.23.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.23.0 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.23.1 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.23.1 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
+npx -y @hue-run/sdk@0.23.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.23.1 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -986,7 +986,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.23.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.23.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/README.md

@@ -552,8 +552,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.23.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.23.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.23.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3
@@ -1325,7 +1325,7 @@ existing-provider flush callbacks and recovery. Local/CI runners remain availabl
 
 ## Serving safely
 
-Use `createHueSafe(options)` for best-effort startup. Invalid initialization returns a disabled client that keeps your `onExportIssue` hook and records the reason as an instrumentation failure. Pass `enabled: false` to disable Hue without a key or a `captureContent` choice; disabled helpers still execute the application callback, and `inject()` keeps propagating the application's own trace context. `flushSafe({ timeoutMillis: 1000 })` and `shutdownSafe({ timeoutMillis: 1000 })` return `{ ok, timedOut, report }` without rejecting. Strict initialization, connection checks and `flush()` remain available for diagnostics; do not gate application readiness or responses on them.
+Use `createHueSafe(options)` for best-effort startup. Invalid initialization returns a disabled client that keeps your `onExportIssue` hook and records a fixed initialization-failure diagnostic without inspecting or exposing the original error. Pass `enabled: false` to disable Hue without a key or a `captureContent` choice; disabled helpers still execute the application callback, and `inject()` keeps propagating the application's own trace context. `flushSafe({ timeoutMillis: 1000 })` and `shutdownSafe({ timeoutMillis: 1000 })` return `{ ok, timedOut, report }` without rejecting. Strict initialization, connection checks and `flush()` remain available for diagnostics; do not gate application readiness or responses on them.
 
 Capture/serialization/redaction/provider failures omit unsafe telemetry, record failures, and preserve the original business result/error. Async diagnostic rejections are contained; diagnostics are rate-limited. The default `maxQueueBytes` is 8 MiB across traces/logs including in-flight work, alongside the existing record cap. `pendingBytes` is a current queue gauge; `droppedSpans`, `droppedLogs` and `instrumentationFailures` are cumulative failure counters; `uploadedValues` and `uploadFallbacks` count completed uploads and upload fallbacks for whole attributes, eligible binary or large text media, and opt-in `recordFile` uploads. Whole-attribute fallbacks refused at export keep a prefix; media fallbacks keep a digest; helper upload fallbacks keep the file event; a value whose upload failed after export keeps its entry as well. This is a telemetry budget, not a total process memory ceiling. A timeout bounds the caller and does not cancel a borrowed provider. Never retry the business operation to recover telemetry. See [production setup](https://docs.hue.run/sdks/typescript#production-setup).
 

package/dist/client.js

@@ -370,6 +370,8 @@ export class HueClient {
      * provider and surface as `hue.mcp.provider` / `hue.mcp.surface`.
      */
     async tool(name, input, execute, options = {}) {
+        if (!this.enabled || this.closed)
+            return this.withSpan("execute_tool", () => execute());
         const attributes = {
             "gen_ai.operation.name": "execute_tool",
             "gen_ai.tool.name": name,
@@ -380,22 +382,25 @@ export class HueClient {
             // A blank or non-string label is omitted and counted; the tool call itself still runs.
             if (isLabel(value))
                 attributes[key] = value;
-            else if (this.enabled && !this.closed)
+            else
                 this.instrumentationFailed();
         };
-        stamp("gen_ai.tool.call.id", options.callId);
-        stamp("mcp.server.name", options.mcp?.name);
-        stamp("mcp.server.version", options.mcp?.version);
-        stamp("hue.mcp.provider", options.mcp?.provider);
-        stamp("hue.mcp.surface", options.mcp?.surface);
-        if (this.enabled && !this.closed && this.captureContent) {
-            try {
-                if (options.endpoint !== undefined)
-                    Object.assign(attributes, toolEndpointAttributes(options.endpoint));
-            }
-            catch {
-                this.instrumentationFailed();
-            }
+        let spanOptions = { attributes };
+        try {
+            stamp("gen_ai.tool.call.id", options.callId);
+            stamp("mcp.server.name", options.mcp?.name);
+            stamp("mcp.server.version", options.mcp?.version);
+            stamp("hue.mcp.provider", options.mcp?.provider);
+            stamp("hue.mcp.surface", options.mcp?.surface);
+            if (this.captureContent && options.endpoint !== undefined)
+                Object.assign(attributes, toolEndpointAttributes(options.endpoint));
+            spanOptions = {
+                attributes,
+                ...(options.parentContext ? { parentContext: options.parentContext } : {}),
+            };
+        }
+        catch {
+            this.instrumentationFailed();
         }
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
@@ -403,10 +408,7 @@ export class HueClient {
             if (result !== undefined)
                 this.setContent(span, "gen_ai.tool.call.result", result);
             return result;
-        }, {
-            attributes,
-            ...(options.parentContext ? { parentContext: options.parentContext } : {}),
-        });
+        }, spanOptions);
     }
     /**
      * Runs `callback` as a sub-agent: inside an `invoke_agent {name}` span carrying
@@ -420,11 +422,27 @@ export class HueClient {
      * in `withSpan`. A blank or non-string name is recorded as `unknown` and counted.
      */
     async subagent(name, callback, options = {}) {
+        if (!this.enabled || this.closed)
+            return this.withSpan("invoke_agent", callback);
         let agent = name;
         if (!isLabel(name)) {
             agent = "unknown";
-            if (this.enabled && !this.closed)
-                this.instrumentationFailed();
+            this.instrumentationFailed();
+        }
+        let spanOptions = {};
+        try {
+            spanOptions = {
+                ...options,
+                attributes: {
+                    ...options.attributes,
+                    "gen_ai.operation.name": "invoke_agent",
+                    "gen_ai.agent.name": agent,
+                    "hue.agent.role": "subagent",
+                },
+            };
+        }
+        catch {
+            this.instrumentationFailed();
         }
         return this.withSpan(`invoke_agent ${agent}`, async (span) => {
             let outputSet = false;
@@ -438,15 +456,7 @@ export class HueClient {
             if (result !== undefined && !outputSet)
                 span.setOutput(result);
             return result;
-        }, {
-            ...options,
-            attributes: {
-                ...options.attributes,
-                "gen_ai.operation.name": "invoke_agent",
-                "gen_ai.agent.name": agent,
-                "hue.agent.role": "subagent",
-            },
-        });
+        }, spanOptions);
     }
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
@@ -458,24 +468,44 @@ export class HueClient {
      * recorded as `gen_ai.system_instructions` and `gen_ai.tool.definitions`, content like `input`.
      */
     async model(model, callback, options) {
-        // A disabled or closed client creates no span, so invalid metadata is not an instrumentation
-        // failure either; only an active client records it (matching the other helpers).
-        const active = this.enabled && !this.closed;
+        if (!this.enabled || this.closed)
+            return this.withSpan("model", callback);
+        let prepared = { provider: "unknown" };
+        try {
+            prepared = {
+                operation: options?.operation,
+                provider: options?.provider,
+                name: options?.name,
+                sessionId: options?.sessionId,
+                userId: options?.userId,
+                workspaceId: options?.workspaceId,
+                parentContext: options?.parentContext,
+                ...(this.captureContent
+                    ? {
+                        input: options?.input,
+                        systemInstructions: options?.systemInstructions,
+                        tools: options?.tools,
+                    }
+                    : {}),
+            };
+        }
+        catch {
+            this.instrumentationFailed();
+        }
         const label = (value, fallback) => {
             if (isLabel(value))
                 return value;
-            if (active)
-                this.instrumentationFailed();
+            this.instrumentationFailed();
             return fallback;
         };
         const requestModel = label(model, "unknown");
-        const operation = label(options?.operation ?? "chat", "chat");
-        const provider = label(options?.provider, "unknown");
-        const name = options?.name === undefined
+        const operation = label(prepared.operation ?? "chat", "chat");
+        const provider = label(prepared.provider, "unknown");
+        const name = prepared.name === undefined
             ? `${operation} ${requestModel}`
-            : label(options.name, `${operation} ${requestModel}`);
+            : label(prepared.name, `${operation} ${requestModel}`);
         const metadata = { operation, provider, requestModel };
-        const { sessionId, userId, workspaceId, parentContext, input, systemInstructions, tools, } = options ?? {};
+        const { sessionId, userId, workspaceId, parentContext, input, systemInstructions, tools } = prepared;
         return this.withSpan(name, (span) => {
             const handle = {
                 ...span,
@@ -507,22 +537,22 @@ export class HueClient {
     setUsage(span, usage) {
         if (!this.enabled || this.closed)
             return;
-        for (const [key, value] of [
-            ["gen_ai.usage.input_tokens", usage?.inputTokens],
-            ["gen_ai.usage.output_tokens", usage?.outputTokens],
-        ]) {
-            if (value === undefined)
-                continue;
-            if (!Number.isInteger(value) || value < 0) {
-                this.instrumentationFailed();
-                continue;
-            }
-            try {
+        try {
+            for (const [key, value] of [
+                ["gen_ai.usage.input_tokens", usage?.inputTokens],
+                ["gen_ai.usage.output_tokens", usage?.outputTokens],
+            ]) {
+                if (value === undefined)
+                    continue;
+                if (!Number.isInteger(value) || value < 0) {
+                    this.instrumentationFailed();
+                    continue;
+                }
                 span.setAttribute(key, value);
             }
-            catch {
-                this.instrumentationFailed();
-            }
+        }
+        catch {
+            this.instrumentationFailed();
         }
     }
     /**
@@ -1275,11 +1305,10 @@ export function createHueSafe(options) {
     try {
         return new HueClient(options);
     }
-    catch (error) {
-        // The caller's diagnostics hook stays attached and hears why telemetry is off.
+    catch {
+        // Provider errors can contain credentials or expose throwing message accessors.
         const disabled = new HueClient({ enabled: false, onExportIssue: issueCallback(options) });
-        const reason = error instanceof Error && error.message ? error.message : "unknown error";
-        disabled.transport.instrumentationFailure("traces", `Hue is disabled: ${reason.slice(0, 256)}`);
+        disabled.transport.instrumentationFailure("traces", "Hue is disabled: initialization failed");
         return disabled;
     }
 }

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.23.0";
+export declare const sdkVersion = "0.23.1";
 /** OTLP dependency version sent in the export User-Agent. */
 export declare const otlpExporterVersion = "0.223.0";

package/dist/version.js

@@ -1,5 +1,5 @@
 // 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.23.0";
+export const sdkVersion = "0.23.1";
 /** OTLP dependency version sent in the export User-Agent. */
 export const otlpExporterVersion = "0.223.0";

package/package.json

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