@hue-run/sdk 0.20.8 → 0.21.0

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.8`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.21.0`, `@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.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.21.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.21.0 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`
@@ -698,7 +698,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.8.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.21.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -709,7 +709,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.8.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.21.0.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -751,10 +751,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.8 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.8 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.8 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.8 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.21.0 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.21.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.21.0 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.21.0 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
@@ -792,7 +792,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.8 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.21.0 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.
@@ -834,21 +834,28 @@ former; a case failed for its telemetry has `state: "error"`,
 Hue-owned `world_outcome` checks are graded after the world seals. An experiment always covers
 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 Hue's hosted judge budget;
+`hue eval` runs up to four cases at a time by default in one-shot and worker modes.
+`--concurrency 1` runs cases serially. Any explicit `--concurrency` value from 1 to 100 takes precedence.
+Each case keeps its own files, environment and checkpoint.
+
+The CLI requests the run's pinned `llm_judge` evaluators by default after outputs upload,
+before verdict polling, in direct, simulation and worker modes. `--no-judges` skips these requests;
+`--judges` remains accepted for existing commands. 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.
+budget is later disabled. Cases without stored output are excluded. `--no-output` skips judge
+requests, and explicitly combining `--judges` with `--no-output` is refused. Without a pinned
+`llm_judge`, the CLI requests no model jobs. Creating a judge alone does not start one.
+`--check` creates no judge jobs.
 
-With `--judges --wait 0`, the CLI requests the jobs and returns their current verdict state;
+With `--wait 0`, the CLI requests the jobs and returns their current verdict state;
 pending jobs continue in Hue. Uploaded outputs are checkpointed before the attempt or worker
 queue is marked completed. If this handoff or dispatch fails, or its acknowledgement is lost,
 rerun the unchanged command with the same checkpoint directory. The CLI resumes judging the uploaded
-outputs without invoking the agent, using the same idempotency keys. After dispatch succeeds,
+outputs without invoking the agent, using the same idempotency keys. Changing to `--no-judges`
+or `--no-output` while that handoff is pending stops before a new agent run. After dispatch succeeds,
 the next ordinary invocation starts a new run as usual.
 
-`--worker --judges` discards cancelled or released handoffs. Once judge requests succeed, a
+`--worker` discards cancelled or released judge handoffs. Once judge requests succeed, a
 verdict-read failure is logged and the worker keeps accepting runs.
 
 `--command "<shell command>"` spawns the command once per case with the world's environment

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 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.
+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. [`hue eval`](./CLI.md#evaluate-an-agent-against-a-case) dispatches pinned model judges by default after outputs upload; `--no-judges` skips them. Creating or publishing a judge alone starts no model job. `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

@@ -202,6 +202,22 @@ helpers (`setInput`, `setOutput`, `tool` arguments and results, `recordMessages`
 that is not JSON, such as a `Date` or a class instance, is omitted with an instrumentation failure
 while the callback result is returned unchanged.
 
+### Tool endpoint evidence (unreleased)
+
+This checkout adds optional `ToolOptions.endpoint`: `{ url, source, method?, captureQueryParameters? }`.
+Use the actual HTTP(S) request URL, client config URL or receipt URL; set `source` to `request`,
+`client_config` or `receipt`. Supply `method` only when known. With content capture enabled,
+Hue records `url.full`, `hue.tool.endpoint.source` and optional `http.request.method` through the
+existing redactor (`attributes.url.full` for the URL). URL userinfo and fragments are removed;
+query values are omitted unless their names appear in `captureQueryParameters`. Credential names
+are rejected even if allowlisted. Duplicate and empty allowed query values remain intact.
+
+Metadata-only mode omits endpoint evidence. Invalid evidence is omitted and counted without
+changing the tool's result or exception. This helper does not observe HTTP automatically or infer
+account identifiers. Do not supply secret-bearing URL paths, and preserve existing masking of
+account identifiers. See the [setup skill](../../skills/hue/SKILL.md#http-tool-endpoint-evidence)
+for dispatcher integration and source checkout requirements.
+
 ## Images, documents and audio
 
 Hue stores the bytes of images, documents and audio apart from the spans and log records that
@@ -536,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.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.8 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.21.0 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.21.0 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
@@ -588,6 +604,79 @@ npx -y @hue-run/sdk@latest traces import upload ./exports.hue-import --authoriza
 See [Import a bundle of existing traces](CLI.md#import-a-bundle-of-existing-traces) for the
 formats, the report, what Hue refuses and the exit codes.
 
+## Sub-agents
+
+Run a sub-agent with `hue.subagent(name, callback, options)`, inside the tool call that starts it:
+
+```ts
+const findings = await hue.tool("research", { topic }, () =>
+  hue.subagent(
+    "researcher",
+    async () => {
+      const notes = await hue.model("gpt-5-mini", () => callModel(topic), { provider: "openai" });
+      return hue.tool("summarize", notes, () => summarize(notes));
+    },
+    { input: topic },
+  ),
+);
+```
+
+The sub-agent runs inside one `invoke_agent researcher` span with `gen_ai.operation.name`
+`invoke_agent`, `gen_ai.agent.name` `researcher` and `hue.agent.role` `subagent`. That span is a
+child of the active span, here the `execute_tool research` span, and the sub-agent's own model and
+tool spans are its children, so Hue scopes them to the sub-agent. Sub-agents nest: a sub-agent's
+tool can start another. The span is `INTERNAL` unless `options.kind` says otherwise; session, user
+and workspace identifiers are inherited unless `options` sets them. `options.input` and the
+callback's defined result are recorded as `input.value` and `output.value` when `captureContent`
+is true (a callback that calls `setOutput` keeps its own output), and errors are recorded and
+rethrown as in `withSpan`.
+
+The calling agent's role is not set for you: Hue reads roles only from the spans that state them,
+and the span a sub-agent starts under is usually a tool call, not the agent. To label the calling
+agent, give its own span the role:
+
+```ts
+await hue.withSpan("invoke_agent planner", () => runPlanner(), {
+  attributes: {
+    "gen_ai.operation.name": "invoke_agent",
+    "gen_ai.agent.name": "planner",
+    "hue.agent.role": "orchestrator",
+  },
+});
+```
+
+When the sub-agent runs in another process, send the caller's trace context with the request and
+start the sub-agent under it:
+
+```ts
+// The calling process, inside the tool call that hands the task over.
+await hue.tool("research", { topic }, async () => {
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  hue.inject(headers); // adds `traceparent` only
+  const response = await fetch(researcherUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ topic, sessionId }),
+  });
+  return response.json();
+});
+
+// The sub-agent's process, for example an Express handler.
+const { topic, sessionId } = req.body;
+const findings = await hue.subagent("researcher", () => research(topic), {
+  parentContext: hue.extract(req.headers),
+  sessionId,
+});
+```
+
+The `invoke_agent researcher` span then belongs to the caller's trace, with the caller's
+`execute_tool research` span as its parent. `hue.extract()` reads a plain header object such as
+Node's `req.headers`; pass `Object.fromEntries(request.headers)` for a Fetch `Request`. Only
+`traceparent` crosses the boundary, never the API key, baggage or the session, so pass the
+session identifier yourself as above. Accept `traceparent` only from your own services: whoever
+sets it chooses the trace the sub-agent's spans join. On an endpoint that also serves other
+callers, extract it only from authenticated internal requests and start a new trace otherwise.
+
 ## Vercel AI SDK 6
 
 AI SDK 6 accepts a per-call tracer through `experimental_telemetry`. Pass
@@ -782,7 +871,8 @@ and similar attributes on your own providers.
 
 For external parent context pass `parentContext` to `withSpan`. Across processes, use
 `hue.inject(carrier)` inside the producing span and `hue.extract(carrier)` in the worker; both
-speak W3C `traceparent` only and never include the API key or baggage. Hue registers no global
+speak W3C `traceparent` only and never include the API key or baggage. Extract it only from
+trusted internal callers, as described under [Sub-agents](#sub-agents). Hue registers no global
 propagator, so `propagation.inject()` from `@opentelemetry/api` is a no-op unless your
 application configured one. `getContext()` exposes the helper's current context for APIs taking
 an explicit context. Session, user and workspace identifiers (`sessionId` as

package/dist/cli/eval.js

@@ -92,15 +92,16 @@ Output and limits:
   --check                         One-shot: check the key, selection and agent, print what the
                                   run would do and exit without creating a run or a world
   --checkpoint-dir <path>         Private checkpoint directory (default: .hue/eval/<agent-key>)
-  --concurrency <n>               Cases in flight, 1-100 (default: 1)
+  --concurrency <n>               Cases in flight, 1-100 (default: 4)
   --trace-not-accepted <policy>   A case whose telemetry Hue did not accept in time: fail_case
                                   (default) completes it as failed with the evidence omitted;
                                   pending completes it in its true state with the trace still to
                                   arrive, which Hue attaches once its export is complete
   --timeout <seconds>             Per-case --command timeout (default: 600)
   --wait <seconds>                Verdict wait after the run finishes (default: 300)
-  --judges                        Request pinned hosted model judges after outputs upload
-                                  (off by default; uses the project's judge budget)
+  --no-judges                     Skip pinned hosted model judges (requested by default
+                                  after outputs upload; uses the project's judge budget)
+  --judges                        Request pinned judges (compatibility flag)
   -h, --help                      Show this help
 
 HUE_API_KEY must be a "Read and write" project key; it is never printed.
@@ -154,7 +155,8 @@ function parse(argv) {
                 content: { type: "boolean" },
                 "no-content": { type: "boolean", default: false },
                 "no-output": { type: "boolean", default: false },
-                judges: { type: "boolean", default: false },
+                judges: { type: "boolean" },
+                "no-judges": { type: "boolean", default: false },
                 "trace-not-accepted": { type: "string" },
                 "save-version": { type: "boolean", default: false },
                 check: { type: "boolean", default: false },
@@ -1123,6 +1125,19 @@ export async function dispatchPinnedJudges(client, experimentId, subjectIds, sig
         await dispatch();
     return count;
 }
+/** Keep the judge lock through execution so an opt-out cannot race a pending dispatch. */
+async function acquireJudgeCheckpoint(directory, projectId, baseUrl, enabled) {
+    const store = await CheckpointStore.acquire(checkpointPath(directory, ["judge-dispatch", "judge checkpoint"]), { kind: "cli-judge-dispatch", projectId, baseUrl });
+    try {
+        if (!enabled && (await store.read("pending")))
+            throw new Error("Recover the pending hosted checks with the original flags before using --no-judges or --no-output");
+        return store;
+    }
+    catch (error) {
+        await store.release();
+        throw error;
+    }
+}
 /** Durable handoff before the original attempt marker or queue acknowledgement. */
 async function checkpointJudges(judging, run, completion) {
     await judging.store.write("pending", {
@@ -1242,7 +1257,7 @@ function parseBaseline(value) {
 }
 async function runOnce(values, connection, agents, agent, hue, output, signal) {
     const client = new EvaluationClient(connection);
-    const concurrency = integer("concurrency", values.concurrency, 1, 1, 100);
+    const concurrency = integer("concurrency", values.concurrency, 4, 1, 100);
     const baselineId = parseBaseline(values.baseline);
     const mode = parseMode(values.mode);
     integer("wait", values.wait, 300, 0, 86_400);
@@ -1267,9 +1282,10 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
     // Each kind of run has its own checkpoint directory and identity: a mixed run never resumes
     // from, or is resumed by, a direct or simulation run's checkpoint.
     const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, selection.kind);
+    const judgeStore = await acquireJudgeCheckpoint(checkpointDirectory, project.id, connection.baseUrl, values.judges === true);
     const judging = values.judges
         ? {
-            store: await CheckpointStore.acquire(checkpointPath(checkpointDirectory, ["judge-dispatch", "judge checkpoint"]), { kind: "cli-judge-dispatch", projectId: project.id, baseUrl: connection.baseUrl }),
+            store: judgeStore,
             selectionDigest: digest({
                 datasetVersionId: pins.datasetVersionId,
                 scorerVersionIds: [...pins.scorerVersionIds].sort(),
@@ -1385,7 +1401,7 @@ async function runOnce(values, connection, agents, agent, hue, output, signal) {
         }, baselineId, output, signal, judging);
     }
     finally {
-        await judging?.store.release();
+        await judgeStore.release();
     }
 }
 /**
@@ -1425,7 +1441,7 @@ async function checkRun(client, values, pins, selection, agent, output) {
         mode: kind,
         worldCases: kind === "direct" ? 0 : worldCases,
         directCases: kind === "direct" ? cases : cases - worldCases,
-        agent: { key: agent.key, revision: agent.revision, concurrency: values.concurrency ?? "1" },
+        agent: { key: agent.key, revision: agent.revision, concurrency: values.concurrency ?? "4" },
     };
     if (values.json)
         process.stdout.write(`${JSON.stringify({ check })}\n`);
@@ -1602,19 +1618,16 @@ async function runWorker(values, connection, agents, agent, hue, output, signal)
     const client = new ObservedClient(connection);
     const environmentClient = createEnvironmentClient(connection);
     const wait = integer("wait", values.wait, 300, 0, 86_400);
-    const concurrency = integer("concurrency", values.concurrency, 1, 1, 100);
+    const concurrency = integer("concurrency", values.concurrency, 4, 1, 100);
     let maxRuns = values["max-runs"] === undefined
         ? undefined
         : integer("max-runs", values["max-runs"], 1, 1, 1_000_000);
     const project = await client.checkConnection();
     const checkpointDirectory = await prepareCheckpointDirectory(values["checkpoint-dir"], agent.key, project.id, "worker", slug(agent.revision) || "dev");
+    const judgeStore = await acquireJudgeCheckpoint(checkpointDirectory, project.id, connection.baseUrl, values.judges === true);
     const judging = values.judges
         ? {
-            store: await CheckpointStore.acquire(checkpointPath(checkpointDirectory, ["judge-dispatch", "judge checkpoint"]), {
-                kind: "cli-judge-dispatch",
-                projectId: project.id,
-                baseUrl: connection.baseUrl,
-            }),
+            store: judgeStore,
             selectionDigest: digest(agent),
             source: {
                 directory: checkpointDirectory,
@@ -1787,7 +1800,7 @@ async function runWorker(values, connection, agents, agent, hue, output, signal)
         return 0;
     }
     finally {
-        await judging?.store.release();
+        await judgeStore.release();
     }
 }
 /**
@@ -1831,8 +1844,11 @@ export async function runEvalCommand(argv) {
         worker = values.worker;
         if (values.content && values["no-content"])
             throw new UsageError("Choose either --content or --no-content");
+        if (values.judges && values["no-judges"])
+            throw new UsageError("Choose either --judges or --no-judges");
         if (values.judges && values["no-output"])
             throw new UsageError("--judges requires stored case outputs; remove --no-output");
+        values.judges = !values["no-judges"] && !values["no-output"];
         // A usage error before anything is prepared or created: no run is left to recover from it.
         traceNotAcceptedPolicy(values["trace-not-accepted"]);
         json = values.json;

package/dist/client.d.ts

@@ -83,6 +83,18 @@ export declare class HueClient {
      * provider and surface as `hue.mcp.provider` / `hue.mcp.surface`.
      */
     tool<T>(name: string, input: unknown, execute: () => Promise<T> | T, options?: ToolOptions): Promise<T>;
+    /**
+     * Runs `callback` as a sub-agent: inside an `invoke_agent {name}` span carrying
+     * `gen_ai.operation.name` `invoke_agent`, `gen_ai.agent.name` and `hue.agent.role` `subagent`.
+     * The span nests under the active span, normally the `tool()` span of the call that started
+     * the sub-agent, or under `options.parentContext`, for example `hue.extract(headers)` in
+     * another process. The sub-agent's own model and tool spans nest under it, and session, user
+     * and workspace identifiers are inherited unless `options` sets them. `options.input` and a
+     * defined result are recorded as `input.value` / `output.value` when `captureContent` is true;
+     * a callback that calls `setOutput` keeps its own output. Errors are recorded and rethrown as
+     * in `withSpan`. A blank or non-string name is recorded as `unknown` and counted.
+     */
+    subagent<T>(name: string, callback: (span: HueSpan) => Promise<T> | T, options?: SpanOptions): Promise<T>;
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
      * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,

package/dist/client.js

@@ -11,6 +11,7 @@ import { defaultResource, resourceFromAttributes } from "@opentelemetry/resource
 import { HUE_SCOPE } from "./config.js";
 import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, providerErrorDescription, } from "./provider-tools.js";
 import { toolCatalogSummary } from "./tool-definitions.js";
+import { toolEndpointAttributes } from "./tool-endpoint.js";
 import { contentLimitsOf, encodeBoundedContent, encodeContent, noopSpan, safeSpan, spanSource, } from "./safety.js";
 import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
 import { countFallback, MAX_BLOB_BYTES, newTally, sizeOf } from "./blobs.js";
@@ -387,6 +388,15 @@ export class HueClient {
         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();
+            }
+        }
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
@@ -398,6 +408,46 @@ export class HueClient {
             ...(options.parentContext ? { parentContext: options.parentContext } : {}),
         });
     }
+    /**
+     * Runs `callback` as a sub-agent: inside an `invoke_agent {name}` span carrying
+     * `gen_ai.operation.name` `invoke_agent`, `gen_ai.agent.name` and `hue.agent.role` `subagent`.
+     * The span nests under the active span, normally the `tool()` span of the call that started
+     * the sub-agent, or under `options.parentContext`, for example `hue.extract(headers)` in
+     * another process. The sub-agent's own model and tool spans nest under it, and session, user
+     * and workspace identifiers are inherited unless `options` sets them. `options.input` and a
+     * defined result are recorded as `input.value` / `output.value` when `captureContent` is true;
+     * a callback that calls `setOutput` keeps its own output. Errors are recorded and rethrown as
+     * in `withSpan`. A blank or non-string name is recorded as `unknown` and counted.
+     */
+    async subagent(name, callback, options = {}) {
+        let agent = name;
+        if (!isLabel(name)) {
+            agent = "unknown";
+            if (this.enabled && !this.closed)
+                this.instrumentationFailed();
+        }
+        return this.withSpan(`invoke_agent ${agent}`, async (span) => {
+            let outputSet = false;
+            const result = await callback({
+                ...span,
+                setOutput: (value) => {
+                    outputSet = true;
+                    span.setOutput(value);
+                },
+            });
+            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",
+            },
+        });
+    }
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
      * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,

package/dist/tool-endpoint.d.ts

@@ -0,0 +1,4 @@
+import type { Attributes } from "@opentelemetry/api";
+import type { ToolEndpoint } from "./types.js";
+/** Copy evidence, never send a request or resolve an endpoint from a tool name. */
+export declare function toolEndpointAttributes(endpoint: ToolEndpoint): Attributes;

package/dist/tool-endpoint.js

@@ -0,0 +1,46 @@
+import { isCredentialKey } from "./tool-definitions.js";
+/** Copy evidence, never send a request or resolve an endpoint from a tool name. */
+export function toolEndpointAttributes(endpoint) {
+    if (!endpoint ||
+        typeof endpoint.url !== "string" ||
+        endpoint.url.length > 8192 ||
+        /[\s\\\p{Cc}]/u.test(endpoint.url) ||
+        /%(?![0-9a-f]{2})/i.test(endpoint.url) ||
+        !["request", "client_config", "receipt"].includes(endpoint.source))
+        throw new Error("Invalid tool endpoint evidence");
+    const url = new URL(endpoint.url);
+    if (!["http:", "https:"].includes(url.protocol))
+        throw new Error("Invalid tool endpoint protocol");
+    const names = endpoint.captureQueryParameters ?? [];
+    if (!Array.isArray(names) ||
+        names.length > 32 ||
+        names.some((name) => typeof name !== "string" ||
+            !/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(name) ||
+            isCredentialKey(name)))
+        throw new Error("Invalid tool endpoint query allowlist");
+    // Keep the raw pairs, including duplicates and empty values. Re-encoding or selecting the
+    // first value can turn missing, malformed or ambiguous routing evidence into a usable ID.
+    const query = url.search
+        .slice(1)
+        .split("&")
+        .filter((pair) => {
+        const key = decodeURIComponent(pair.split("=", 1)[0].replace(/\+/g, " "));
+        return names.includes(key);
+    })
+        .join("&");
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    url.search = query;
+    const attributes = {
+        "url.full": url.href,
+        "hue.tool.endpoint.source": endpoint.source,
+    };
+    if (endpoint.method !== undefined) {
+        if (typeof endpoint.method !== "string" ||
+            !/^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,32}$/.test(endpoint.method))
+            throw new Error("Invalid tool endpoint method");
+        attributes["http.request.method"] = endpoint.method;
+    }
+    return attributes;
+}

package/dist/transport.js

@@ -16,7 +16,7 @@ import { MediaDigestMemo, isMediaName } from "./inline-files.js";
 import { locateParts } from "./attachment.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { DROPPED_RECORDS_KEY, isContentKey, isTruncatedMarker, redactLog, redactSpan, TRUNCATED_KEY, truncatedMarker, withTruncatedKeys, } from "./privacy.js";
-import { sdkVersion } from "./version.js";
+import { otlpExporterVersion, sdkVersion } from "./version.js";
 /** A record's trace: a span's context, a log record's span identifiers; "" when unreadable. */
 function recordTraceId(record) {
     try {
@@ -2021,7 +2021,7 @@ class ReportingExporter {
         await this.forceFlush();
     }
 }
-// OpenTelemetry's OTLP/HTTP transport rules (otlp-exporter-base 0.222), restated because that
+// OpenTelemetry's OTLP/HTTP transport rules, restated because that
 // transport discards response headers, which Hue uses to announce features.
 const MAX_RETRIES = 5;
 const INITIAL_BACKOFF_MILLIS = 1000;
@@ -2042,7 +2042,7 @@ const RETRYABLE_NETWORK_ERRORS = new Set([
     "EHOSTUNREACH",
 ]);
 /** OpenTelemetry's exporter token, which follows Hue's in the User-Agent as it always has. */
-const OTEL_USER_AGENT = "OTel-OTLP-Exporter-JavaScript/0.222.0";
+const OTEL_USER_AGENT = `OTel-OTLP-Exporter-JavaScript/${otlpExporterVersion}`;
 function retryAfterMillis(value) {
     if (value == null)
         return undefined;

package/dist/types.d.ts

@@ -201,11 +201,21 @@ export interface McpServerInfo {
     /** Hue surface such as `google.gmail/mcp`, recorded as `hue.mcp.surface`. */
     surface?: string;
 }
-/**
- * Options for {@link HueClient.tool}. `callId` is the provider-issued tool-call
- * id; `mcp` is the MCP server that handled the call.
- */
+/** Explicit routing evidence for {@link HueClient.tool}; values come from the application. */
+export interface ToolEndpoint {
+    /** Actual HTTP(S) URL used by the tool. Never synthesize it from a tool or server label. */
+    url: string;
+    /** Where the URL was observed. Recorded as `hue.tool.endpoint.source`. */
+    source: "request" | "client_config" | "receipt";
+    /** Actual HTTP method, when known; the SDK supplies no default. */
+    method?: string;
+    /** Non-secret query names to retain, including every occurrence. All others are removed. */
+    captureQueryParameters?: readonly string[];
+}
+/** Options for {@link HueClient.tool}, including call identity and opt-in routing evidence. */
 export interface ToolOptions extends Pick<SpanOptions, "parentContext"> {
+    /** Opt-in routing evidence. Only captured with content enabled, through existing redaction. */
+    endpoint?: ToolEndpoint;
     /** Provider-issued identifier of this tool call, recorded as `gen_ai.tool.call.id`. */
     callId?: string;
     /**

package/dist/version.d.ts

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

package/dist/version.js

@@ -1,3 +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.20.8";
+export const sdkVersion = "0.21.0";
+/** 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.20.8",
+  "version": "0.21.0",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -91,22 +91,22 @@
   },
   "dependencies": {
     "@babel/parser": "7.29.9",
-    "@opentelemetry/api-logs": "0.222.0",
-    "@opentelemetry/core": "2.11.0",
-    "@opentelemetry/otlp-exporter-base": "0.222.0",
-    "@opentelemetry/otlp-transformer": "0.222.0",
-    "@opentelemetry/resources": "2.11.0",
-    "@opentelemetry/sdk-logs": "0.222.0",
-    "@opentelemetry/sdk-trace": "2.11.0",
+    "@opentelemetry/api-logs": "0.223.0",
+    "@opentelemetry/core": "2.12.0",
+    "@opentelemetry/otlp-exporter-base": "0.223.0",
+    "@opentelemetry/otlp-transformer": "0.223.0",
+    "@opentelemetry/resources": "2.12.0",
+    "@opentelemetry/sdk-logs": "0.223.0",
+    "@opentelemetry/sdk-trace": "2.12.0",
     "zod": "^3.25.76 || ^4.6.5"
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.99",
+    "@ai-sdk/otel": "1.0.137",
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/context-async-hooks": "2.11.0",
+    "@opentelemetry/context-async-hooks": "2.12.0",
     "@types/bun": "1.4.2",
     "@types/node": "26.6.4",
-    "ai": "7.0.99",
+    "ai": "7.0.137",
     "ajv": "8.20.0",
     "protobufjs": "8.8.0",
     "typescript": "7.0.2"