@hue-run/sdk 0.20.3 → 0.20.5

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.20.3`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.5`, `@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.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.5 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.5 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`
@@ -523,7 +523,9 @@ attributes Hue reads; an id that is no OpenTelemetry id is mapped as `hue import
 so an export and a live import of the same trace agree. An ATIF export becomes one trace: an agent
 span for the run, a model span per agent step with the conversation so far, a tool span per call,
 each embedded subagent as its own agent span under the call that spawned it, and the export's
-`extra.user_id` as the trace's `user.id`. ATIF records instants, not durations, so model and tool
+`extra.user_id` as the trace's `user.id`; its spans carry `hue.import.format` `atif` under the
+instrumentation scope `hue.import.atif`, and the run's agent span is named `invoke_agent
+<agent.name>` from the export's own agent. ATIF records instants, not durations, so model and tool
 spans are points in time, and a tool's result is kept as text with no error status of the
 importer's making. The same trace in two files is one trace when the copies agree and a refusal
 when they differ; a trace with more than 100,000 spans, 64 batches or 1,000 values is refused and
@@ -687,7 +689,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.20.3.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.5.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -698,7 +700,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.20.3.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.5.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -740,10 +742,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.20.3 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.3 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.20.3 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.3 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.20.5 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.20.5 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.20.5 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.20.5 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
@@ -781,7 +783,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.3 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.5 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -825,7 +827,7 @@ every case of the saved version; there is no case subset.
 
 `--judges` requests the run's pinned
 `llm_judge` evaluators after outputs upload, before verdict polling. It is off by default and
-works in direct, simulation and worker modes. Requests use the project's hosted judge budget;
+works in direct, simulation and worker modes. Requests use Hue's hosted judge budget;
 Hue applies its admission controls to new jobs. An accepted request remains replayable if the
 budget is later disabled. Cases without stored output are excluded, and combining
 `--judges` with `--no-output` is refused. `--check` creates no judge jobs.

package/EVALUATIONS.md

@@ -184,7 +184,7 @@ Scorer deferral shipped in TypeScript `0.3.1`: the local runner executes only th
 
 `world_outcome` pins (`hue.conversion_outcome.v1` and `.v2`, and the `hue.outcome_assertions.v2` and `.v3` case-outcome evaluators, `.v3` with its pinned judge in `config.judge`) run inside Hue and need no local callback or executable source digest. A supporting server owns their execution from saved world evidence. Legacy `local_code` pins still require the exact registered callback; changing the worker cannot convert those immutable pins into hosted ones.
 
-Manual results require a human session. Hosted model-judge dispatch is explicit: call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. Hue checks the project's budget when admitting new requests. `getJudgeBudget()` reports its current state, but replay an interrupted request with the same key and body even if that state changed. The [`hue eval --judges`](./CLI.md#evaluate-an-agent-against-a-case) option performs this dispatch after outputs upload; it is off by default. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
+Manual results require a human session. Hosted model-judge dispatch is explicit: call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. Hue checks its judge budget when admitting new requests. `getJudgeBudget()` reports its current state, and on current servers the organization's monthly AI budget as `organizationBudget`, but replay an interrupted request with the same key and body even if that state changed. The [`hue eval --judges`](./CLI.md#evaluate-an-agent-against-a-case) option performs this dispatch after outputs upload; it is off by default. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
 
 When present, the budget's `authentication` reports credential resolution only. An
 `available` status or `configured: true` does not prove that a provider accepted the

package/README.md

@@ -536,8 +536,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.3 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.5 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.5 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

package/dist/cli/traces-import-convert.js

@@ -992,10 +992,21 @@ function convertLangfuseTrace(draft, traceId) {
 /** The ATIF reader's bounds: a text export of at most 4 MiB and 2,000 spans. */
 export const MAX_ATIF_FILE_BYTES = 4 * 1024 * 1024;
 export const MAX_ATIF_SPANS = 2000;
-const ATIF_IMPORT_VERSION = "2";
-/** The format and scope names Hue reads ATIF-imported spans by (their recorded step order). */
-const ATIF_FORMAT = "auctor.atif";
-const ATIF_SCOPE = "hue.auctor.atif-import";
+/** The conversion's generation, part of every derived trace and span id: raised when the ids'
+ * seed or the spans' shape changes, so a bundle prepared by an earlier generation is prepared
+ * again rather than mixed with this one. 3 names the format generically; 2 carried one
+ * producer's name in the label, the scope and the seed. */
+const ATIF_IMPORT_VERSION = "3";
+/** The format label (`hue.import.format`) and instrumentation scope of a trace converted from
+ * ATIF, the Agent Trajectory Interchange Format: the format's own name, whoever exported it. */
+const ATIF_FORMAT = "atif";
+const ATIF_SCOPE = "hue.import.atif";
+/** The agent span's name, from the export's own agent: `invoke_agent <agent.name>`, or
+ * `invoke_agent` alone when the export names none. */
+function agentSpanName(t) {
+    const name = typeof t.agent.name === "string" ? t.agent.name.trim() : "";
+    return name ? `invoke_agent ${name}` : "invoke_agent";
+}
 const optionalText = z.string().nullable().optional();
 const identity = z.string().min(1).max(512);
 const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).nullable().optional();
@@ -1339,8 +1350,10 @@ export function convertAtifExport(source, rawBytes) {
             for (const sub of spawned.get(requested.tool_call_id) ?? [])
                 order.set(sub, sub.steps.map(() => ordinal++));
     }
+    // The trace's identity is run scoped: the scope name, the conversion's generation, the
+    // export's session and trajectory ids. Never a path, a file digest or a producer's name.
     const identityParts = [
-        ATIF_FORMAT === "auctor.atif" ? "hue.auctor.atif" : ATIF_FORMAT,
+        ATIF_SCOPE,
         ATIF_IMPORT_VERSION,
         document.session_id,
         document.trajectory_id ?? null,
@@ -1404,7 +1417,7 @@ export function convertAtifExport(source, rawBytes) {
     addUsage(rootAttributes, finalUsage(document));
     addSpan({
         spanId: rootId,
-        name: "invoke_agent auctor",
+        name: agentSpanName(document),
         startTimeUnixNano: main.start,
         endTimeUnixNano: lastInstant,
         attributes: rootAttributes.finish(),
@@ -1543,7 +1556,7 @@ export function convertAtifExport(source, rawBytes) {
         addSpan({
             spanId: agentId,
             parentSpanId,
-            name: `invoke_agent ${sub.agent.name}`,
+            name: agentSpanName(sub),
             startTimeUnixNano: found.checked.start,
             endTimeUnixNano: found.checked.times.at(-1),
             attributes: attributes.finish(),

package/dist/evals/types.d.ts

@@ -502,6 +502,31 @@ export interface JudgeBudget {
     maxInFlight: number;
     /** Dispatch is currently blocked. */
     blocked: boolean;
+    /** Micro-USD the organization's monthly AI budget can still admit; absent on older servers. */
+    organizationAvailableMicroUsd?: number;
+    /** The organization's monthly AI budget (one UTC calendar month), which hosted judging draws on.
+     * Amounts are decimal USD strings. Absent on older servers; `null` when there is no organization
+     * budget to report. */
+    organizationBudget?: {
+        /** The month's allowance. */
+        monthlyAllowanceUsd: string;
+        /** Settled spend this month. */
+        actualSpendUsd: string;
+        /** Reserved by calls in flight. */
+        reservedUsd: string;
+        /** Held by calls whose cost is not known yet. */
+        unresolvedUsd: string;
+        /** Calls whose cost is not known yet. */
+        unresolvedCalls: number;
+        /** What the month can still admit. */
+        remainingUsd: string;
+        /** First day of the month, `YYYY-MM-DD`. */
+        periodStart: string;
+        /** When the next month starts, as an ISO 8601 timestamp. */
+        resetsAt: string;
+        /** No more AI work is admitted this month. */
+        paused: boolean;
+    } | null;
 }
 /** A scorer and its published versions. */
 export interface Scorer extends Identity {

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

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

package/package.json

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