@hue-run/sdk 0.1.4 → 0.2.0

package/ENVIRONMENTS.md

@@ -0,0 +1,182 @@
+# Simulated environments
+
+Install the optional evaluation runtime-contract peer with the SDK:
+
+```bash
+npm install @hue-run/sdk zod
+```
+
+Your agent runs in your process while a disposable simulated world runs in Hue. The world is
+authoritative and records an ordered journal; Hue does not execute your agent code or provider
+credentials.
+
+## Run a scenario like a test
+
+`runSimulation` is the one-shot developer path. It calls your existing callback directly, so
+IDE breakpoints and cooperative cancellation work. It does not register a worker, poll for jobs,
+host your laptop or require an inbound tunnel.
+
+```ts
+import { createHue } from "@hue-run/sdk";
+import { createEnvironmentClient } from "@hue-run/sdk/environment";
+import { createEvaluationClient, runSimulation } from "@hue-run/sdk/evals";
+
+const connection = { apiKey: process.env.HUE_API_KEY! };
+const hue = createHue({ ...connection, serviceName: "agent-test", captureContent: true });
+
+try {
+  const report = await runSimulation({
+    client: createEvaluationClient(connection),
+    environmentClient: createEnvironmentClient(connection),
+    hue,
+    checkpointDirectory: ".hue-checkpoints/refund-scenario",
+    scenario: { kind: "experiment", experimentId: process.env.HUE_EXPERIMENT_ID! },
+    persistResultContent: true,
+    traceEvidence: { mode: "required" },
+    target: (inputs, { tools, mcp, config, signal }) =>
+      runMyExistingAgent({ inputs, config, tools, mcp, signal }),
+    onProgress(event) {
+      if (event.type === "run_created") console.log(`Inspect this run: ${event.runUrl}`);
+    },
+  });
+  console.log(report.runUrl);
+} finally {
+  await hue.shutdownSafe();
+}
+```
+
+The referenced app-authored experiment is a template. Each completed invocation clones its
+exact frozen dataset, configuration and scorer-version pins into a fresh experiment and creates
+one isolated world per case. An interrupted invocation resumes through the private checkpoint
+directory. If the agent may have run without a saved outcome, resume fails explicitly and never
+calls it again. If Hue cannot confirm whether the world sealed, the execution likewise stays
+uncertain and a resume refuses to re-invoke the agent.
+
+`tools` contains framework-neutral local callables. `mcp` is a short-lived bearer for the same
+run's closed catalog when a model provider executes MCP remotely. It is scoped to one execution
+and world and is not the Hue project key. Configuration alone does not redirect real provider
+calls; give one of these connections to the agent's actual tool boundary. `environmentRunId`
+identifies the same world for adapter control operations such as
+`environmentClient.recordCoverageGap`; it is not a credential. The MCP token is delivered only
+to the callback and is never written to checkpoints.
+
+### Pinned provider-profile preflight
+
+An experiment with an immutable `attemptBaselineV2` can require the local process to describe
+the agent configuration it is actually about to run. Supply `actualAgentManifest`, the exact
+ordered `requestedProviders`, and an `mcpSurface` selected from that request. Hue compares the
+agent, prompt, model, tools, approvals, orchestration, MCP catalogs and native-helper
+configuration before the callback or model runs. Missing evidence stays explicitly `missing`; it
+is never treated as a match.
+
+On a ready decision, `context.connectionBundle` contains the selected V2 provider surfaces and
+`context.mcp` remains the backwards-compatible projection of the selected MCP surface. Endpoints,
+bearers, expiry and credential generation stay in callback memory: the runner does not write
+them to checkpoints or progress events, and it never mutates global `process.env`. A durable
+`environment_incomplete` decision skips both the callback and scoring. If a ready response or
+world seal cannot be confirmed, the checkpoint remains uncertain and resume neither reacquires
+credentials nor invokes the callback again.
+
+This is currently a control-plane contract. Hue can issue provider endpoints under
+`/api/v1/provider-facades/{bindingId}/{grantId}`, but a provider data-plane facade call has not
+yet been proven by the released integration. The existing generic Hue MCP capability remains the
+runnable hosted-tool path; do not interpret preparation or local-tool tests as evidence of a
+hosted Gmail or Slack MCP call.
+
+## Repository-authored scenarios
+
+Repository scenarios publish through the same validated environment, dataset, scorer and
+experiment APIs as Hue-authored scenarios. Stable slugs reuse matching immutable content
+digests; changed definitions, tasks or scorers publish new versions. Hue does not synchronize
+files back from its UI, and the helper refuses an unrelated mutable dataset draft instead of
+overwriting it.
+
+Repository publication supports the public `ScorerDefinition` union: exact match, includes,
+JSON Schema, local code, manual and model-judge definitions. `runSimulation` applies the same
+identity-affecting defaults as Hue before resolving versions and rejects unknown or server-only
+kinds. In particular, `document_verifier` is not part of this SDK contract and is rejected rather
+than published with a guessed digest.
+
+```ts
+const scenario = {
+  kind: "repository" as const,
+  name: "Refund an eligible charge",
+  slug: "refund-eligible-charge",
+  environment: {
+    name: "Refund fixture",
+    slug: "refund-fixture",
+    definition: refundWorld,
+  },
+  cases: [
+    {
+      externalKey: "eligible-charge",
+      inputs: { request: "Refund charge ch_2" },
+      metadata: { suite: "billing" },
+    },
+  ],
+  scorers: [{ name: "Refund saved", slug: "refund-saved", scorer: refundScorer }],
+  config: { agentMode: "support" },
+};
+
+await runSimulation({
+  client,
+  environmentClient,
+  hue,
+  checkpointDirectory: ".hue-checkpoints/refund-scenario",
+  scenario,
+  persistResultContent: false,
+  traceEvidence: { mode: "required" },
+  target: (inputs, context) => runMyExistingAgent({ inputs, ...context }),
+});
+```
+
+Repeat the command after an edit for a fresh attempt and world. The run URL joins task, trace,
+world effects, final state, target outcome and scorer results. Target failures and cancellations
+seal the world as `abandoned`; scorer errors remain separate. Cancellation is cooperative, so
+pass `context.signal` into the provider or agent call.
+
+## Direct environment tools
+
+For lower-level use, create a run and bind its generated catalog:
+
+```ts
+import { randomUUID } from "node:crypto";
+import { bindEnvironmentTools, createEnvironmentClient } from "@hue-run/sdk/environment";
+
+const client = createEnvironmentClient(connection);
+const run = await client.createRun({
+  idempotencyKey: randomUUID(),
+  environmentVersionId,
+});
+const tools = bindEnvironmentTools({ hue, client, run });
+await tools.refund_charge!.execute({ charge_id: "ch_2" });
+await client.finishRun(run.id, { idempotencyKey: randomUUID(), status: "completed" });
+```
+
+An observation with `status: "error"` is a recorded world answer, not a transport exception.
+Run mutations retry with stable invocation/idempotency identities. Registry writes do not retry
+automatically because identity creation and publication have no request key.
+
+## Coverage gaps
+
+A provider adapter can record a known valid provider request that the environment cannot
+implement with `client.recordCoverageGap(run.id, { idempotencyKey, provider, operation, code,
+args, description })`. Use a durable UUID idempotency key and repeat the identical request to
+recover a lost acknowledgement. This is a runner/adapter control operation, not an agent tool.
+Arguments must be a JSON object of at most 16,000 encoded bytes.
+
+Hue preserves the first report, marks `validity: "environment_incomplete"`, and refuses new
+actions while still replaying already-recorded invocation receipts. `coverageGap` retains the
+request and reporting provenance. An absent gap means `not_assessed`; it does not establish
+provider parity.
+
+Local scoring and historical rescoring skip incomplete evidence before calling a scorer, even
+when the target returned no output or failed. Unsupported caller syntax and real provider errors
+are not automatically coverage gaps; the adapter must identify a known missing provider
+behavior. `runSimulation` checks the authoritative world when its callback throws: a durably
+recorded gap finishes as environment-incomplete rather than `TargetError`, while a gap or seal
+that cannot be confirmed stays uncertain and never causes the agent to be replayed.
+
+The hosted MCP connection exposes Hue's bounded native actions; it is not general Gmail or
+Slack HTTP parity and does not proxy arbitrary provider traffic. Forking, in-place reset and
+arbitrary-step diffs are outside this interface.

package/EVALUATIONS.md

@@ -1,5 +1,12 @@
 # Local evaluations
 
+Install the optional runtime-contract peer with the SDK before importing
+`@hue-run/sdk/evals`:
+
+```bash
+npm install @hue-run/sdk zod
+```
+
 The SDK executes targets and scorers on your machine. Hue stores pinned definitions, experiment progress and results. It does not execute uploaded source code. Follow the [installation guide](https://docs.hue.run/installation) to add `@hue-run/sdk` to your application.
 
 ```ts
@@ -63,6 +70,11 @@ try {
 
 Create another experiment with the same frozen version and different `config` to compare configurations. The runner reads the exact experiment case/version and scorer definitions; it never resolves a mutable latest version. `rescore` accepts an existing evaluation-run ID and has no target callback. Subject IDs refer to immutable saved outputs and trace evidence.
 
+For the shorter agent-against-a-hosted-world workflow, use `runSimulation`. It owns immutable
+resolution, a fresh linked world per case, local and hosted MCP tools, finalization, sealed
+evidence and scoring while retaining this runner's checkpoint guarantees. See
+[Simulated environments](ENVIRONMENTS.md#run-a-scenario-like-a-test).
+
 ## Content and result states
 
 Both choices are required and independent:

package/README.md

@@ -1,9 +1,19 @@
+<p align="center">
+  <img alt="Hue" src="https://raw.githubusercontent.com/hue-run/hue-sdk/df0443f98c6096ff331fd0400715e4f3a1936607/.github/assets/hue-ascii-neutral.png" width="720">
+</p>
+
 # Hue TypeScript SDK
 
-A Node 24 / Bun 1.3.9 client for Hue's standard OTLP HTTP endpoints. It uses the
+[![npm](https://img.shields.io/npm/v/%40hue-run%2Fsdk?label=%40hue-run%2Fsdk)](https://www.npmjs.com/package/@hue-run/sdk) ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+
+A client for Hue's standard OTLP HTTP endpoints on Node.js 22 or 24 and Bun 1.4.2. It uses the
 OpenTelemetry JavaScript SDK and official OTLP protobuf exporter components for
 traces and correlated logs. The package is named `@hue-run/sdk`.
 
+[Documentation](https://docs.hue.run) · [Sign in](https://app.hue.run)
+
+_Hue (hue.run) is a tracing and evaluation platform for AI agents. It is not affiliated with Philips Hue / Signify smart lighting or Cloudera Hue._
+
 ## Install
 
 ```bash
@@ -16,7 +26,8 @@ Or with Bun:
 bun add @hue-run/sdk
 ```
 
-Run the command in your application's server package. See the [compatibility guide](https://docs.hue.run/sdks/compatibility) before adding Hue to an application with existing OpenTelemetry or AI SDK dependencies.
+Run the command in your application's server package. The package is ESM; CommonJS applications on
+Node.js 22.12 or later load it with `require("@hue-run/sdk")`. See the [compatibility guide](https://docs.hue.run/sdks/compatibility) before adding Hue to an application with existing OpenTelemetry or AI SDK dependencies.
 
 ## Start
 
@@ -52,9 +63,90 @@ await hue.shutdown(); // flushes and releases providers owned by this client
 The default destination is `https://app.hue.run`. Data goes to
 `/api/v1/otlp/v1/traces` and `/api/v1/otlp/v1/logs` with a Bearer project key.
 Set `baseUrl` only for another Hue deployment. It must be an origin without an API path; a trailing slash is accepted.
-HTTPS is required except for loopback HTTP. Redirects are refused for both
-project checks and exports. There is no proprietary tracing protocol, lab API
-wrapper, database dependency, or dependency on the Hue application workspace.
+HTTPS is required except for loopback HTTP or the explicit
+[`allowInsecureHttp`](#local-development-without-a-hue-account) opt-in. Redirects are refused for both
+project checks and exports.
+
+`checkConnection()` rejects with `HueConnectionError`: its fixed message is safe to log, `status`
+carries the HTTP status when Hue answered, and `cause` carries the underlying network, timeout or
+parsing error. `serviceVersion` and `resourceAttributes` (for example
+`{ "deployment.environment.name": "production", "service.namespace": "agents" }`) describe the
+deployment; a client that owns its providers merges them into its resource, with `serviceName`
+and `serviceVersion` taking precedence over same-named keys.
+
+## Model spans without a framework adapter
+
+When you call a provider SDK directly, `hue.model()` creates the GenAI client span for the call.
+Inside it, `setInput` and `setOutput` record `gen_ai.input.messages` / `gen_ai.output.messages`
+when `captureContent` is true. Those attributes carry the OpenTelemetry GenAI message shape
+(`{ role, parts: [{ type: "text", content }] }`, with `finish_reason` on output messages) defined
+by the semantic conventions'
+[input messages](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.0/docs/gen-ai/gen-ai-input-messages.json)
+and
+[output messages](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.0/docs/gen-ai/gen-ai-output-messages.json)
+JSON schemas, so any semantic-convention-aware backend can read them. Convert provider-native
+messages before recording them:
+
+```ts
+await hue.model(
+  "gpt-5-mini",
+  async (span) => {
+    span.setInput(
+      messages.map((message) => ({
+        role: message.role,
+        parts: [{ type: "text", content: message.content }],
+      })),
+    );
+    const response = await openai.chat.completions.create({ model: "gpt-5-mini", messages });
+    span.setOutput(
+      response.choices.map((choice) => ({
+        role: choice.message.role,
+        parts: [{ type: "text", content: choice.message.content ?? "" }],
+        finish_reason: choice.finish_reason,
+      })),
+    );
+    span.setUsage({
+      inputTokens: response.usage?.prompt_tokens,
+      outputTokens: response.usage?.completion_tokens,
+    });
+    return response;
+  },
+  { provider: "openai" },
+);
+```
+
+The span is named `{operation} {model}` (`operation` defaults to `chat`) with
+`gen_ai.operation.name`, `gen_ai.request.model` and `gen_ai.provider.name`. Like `withSpan`, the
+options come after the callback and also accept `name`, `sessionId`, `userId`, `input` (recorded as
+`gen_ai.input.messages`) and `parentContext`. `setUsage` records
+nonnegative integer `gen_ai.usage.input_tokens` / `output_tokens`; other values are omitted and
+counted as instrumentation failures. Unknown usage stays absent. `hue.tool(name, input, execute)`
+creates an `execute_tool {name}` span with `gen_ai.tool.name`, arguments and result; an optional
+fourth argument `{ callId }` records the provider's tool call id as `gen_ai.tool.call.id`. Content
+helpers (`setInput`, `setOutput`, `tool` arguments and results, `recordMessages`,
+`SpanOptions.input`) accept any value and encode plain JSON data (`JsonValue`) at runtime; a value
+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.
+
+## Vercel AI SDK 6
+
+AI SDK 6 accepts a per-call tracer through `experimental_telemetry`. Pass
+`hueExperimentalTelemetry(hue)` from the core entry point; the generated spans parent under
+`withSpan`, inherit session/user identifiers, and record prompts and responses only when
+`captureContent` is true:
+
+```ts
+import { hueExperimentalTelemetry } from "@hue-run/sdk";
+
+const result = await generateText({
+  model,
+  prompt,
+  experimental_telemetry: hueExperimentalTelemetry(hue),
+});
+```
+
+This requires no `@ai-sdk/otel` peer. `hueTelemetry` remains AI SDK 7 only: it reads the
+installed `ai` major version once per process and throws a `TypeError` below 7.
 
 ## Vercel AI SDK 7
 
@@ -93,7 +185,7 @@ Reuse the client across server requests. Await stream completion before flushing
 returning a streaming `Response` does not mean its stream has finished. The
 [Next.js streaming recipe](https://docs.hue.run/integrations/opentelemetry#flush-streamed-responses-in-next-js)
 shows how to keep completion and flushing within the request's background lifetime.
-For a standalone script, put the operation in `try` and call `await hue.shutdown()`
+For a standalone script, put the operation in `try` and call `await hue.shutdownSafe()`
 in `finally`. Shut down a shared server client only when the application stops.
 
 The integration creates real Vercel provider, streaming and tool spans and passes
@@ -110,27 +202,38 @@ normal OTel setup; Hue does not silently replace it.
 `captureContent: false` disables manual input/output/messages/tool content and
 removes recognized GenAI, Vercel, OpenInference and OpenLLMetry content attributes,
 legacy GenAI content events, log bodies, status messages and exception text before
-export. Model/provider/token metadata remains available. Generic custom attribute
+export. The exported `contentPrefixes` array lists the attribute keys (and their dotted
+children) that are removed. Model/provider/token metadata remains available. Generic custom attribute
 names cannot be classified automatically; use them deliberately.
 
 `captureContent: true` captures supplied content. Accepted content is stored by Hue;
 there is no SDK retention timer or automatic content expiry. To redact strings
 before export, supply `redact(value, path)`; it applies to supported strings in
 attributes, resources, event/link attributes and log bodies. Return a string.
-A throwing callback or invalid/oversized content fails closed: that record is
-counted as failed and the flush reports it. Shared resources are redacted once per
+Invalid/oversized helper content is omitted with an instrumentation failure; the span can still be delivered. Export-time redactor failures reject the affected record and are reported by flush. Shared resources are redacted once per
 export batch. Do not put user content or secrets in span names or scope names.
 
 Manual helpers encode JSON values without converting null into absence. Unknown
-outputs and usage remain absent. This SDK does not estimate tokens or cost. Error
-helpers mark span status and record an exception; thrown application errors remain
-errors and are rethrown unchanged. `withSpan` ends its span in `finally`.
+outputs and usage remain absent. This SDK does not estimate tokens or cost. A thrown
+application error marks the span with `error.type` (the error's `name`), an ERROR status and an
+`exception` event carrying only the type; exception messages and stack traces are never recorded by
+the helpers, whatever `captureContent` is, and the error is rethrown unchanged. `withSpan` ends its
+span in `finally`.
+
+`recordMessages` emits the `gen_ai.client.inference.operation.details` log record correlated with
+the active span, with the messages in its body. The record also carries `gen_ai.operation.name`,
+`gen_ai.provider.name` and `gen_ai.request.model` as attributes, copied from the enclosing
+`hue.model()` span or passed as `operation`, `provider` and `model`, and `gen_ai.conversation.id`
+from the active session, so a collector fan-out to another GenAI-aware backend keeps the request
+context.
 
 ## Existing OpenTelemetry providers
 
 Attach processors while constructing your providers. Hue uses local async context
 for its own helpers and never registers/replaces the global tracer, logger, or
-context manager.
+context manager. When your application has registered a context manager, Hue helpers also make
+their span the active OpenTelemetry span for the duration of the callback, so spans from other
+instrumentations (HTTP clients, provider SDKs) that use the global API parent under it.
 
 ```ts
 import { TracerProvider } from "@opentelemetry/sdk-trace";
@@ -150,10 +253,60 @@ await hue.shutdown(); // flushes; does not shut down these externally owned prov
 // During application shutdown, shut down your providers, then await transport.shutdown().
 ```
 
-For external parent context pass `parentContext` to `withSpan`, or use standard
-OTel context propagation in your application. `getContext()` exposes the helper's
-current context for APIs taking an explicit context. Session/user identifiers are
-inherited within a client callback. Separate requests require separate callbacks.
+The application's providers own the resource in this mode, so `resourceAttributes` on the
+transport options is ignored and reported as a `warning` issue; set `deployment.environment.name`
+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
+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 identifiers are inherited within a client callback and are
+stamped only on spans created through Hue's tracer (helpers and the AI SDK adapters); spans from
+other instrumentations on a shared provider carry them only if that instrumentation sets them.
+Separate requests require separate callbacks.
+
+In attach mode Hue's span processor exports every span that ends on that provider, the same
+default as other OpenTelemetry exporters. To send only part of a provider's spans, wrap the
+processor:
+
+```ts
+const aiSpansOnly = {
+  onStart: () => {},
+  onEnd: (span) => {
+    if ("gen_ai.operation.name" in span.attributes || span.name.startsWith("ai."))
+      transport.spanProcessor.onEnd(span);
+  },
+  forceFlush: () => transport.spanProcessor.forceFlush(),
+  shutdown: () => transport.spanProcessor.shutdown(),
+};
+```
+
+## Local development without a Hue account
+
+Hue speaks standard OTLP, so any local collector works. Point `baseUrl` at a loopback receiver
+that accepts `/api/v1/otlp/v1/traces` and `/api/v1/otlp/v1/logs` (for example an OpenTelemetry
+Collector `otlp` receiver with `http.traces_url_path` and `logs_url_path` set to those paths,
+forwarding to Jaeger or the debug exporter) and pass any placeholder `apiKey`; HTTP is allowed
+for loopback origins. `checkConnection()` and `verifyTrace()` are Hue-only diagnostics and are
+not available against a generic collector.
+
+A collector on a private network is not loopback: a docker-compose sibling such as
+`http://otel-collector:4318` or an in-cluster service requires the explicit opt-in
+`allowInsecureHttp: true`. The client then records a one-time `warning` issue because the key and
+telemetry travel unencrypted. Use a placeholder key with such a collector, and never enable the
+option for a real project key on a network you do not control.
+
+```ts
+const hue = createHue({
+  apiKey: "local-placeholder",
+  serviceName: "my-agent",
+  captureContent: true,
+  baseUrl: "http://otel-collector:4318",
+  allowInsecureHttp: true,
+});
+```
 
 ## Delivery behavior
 
@@ -165,7 +318,7 @@ flush. This is an in-memory queue, not durable storage.
 
 `flush()` waits for the current trace and log export work. A partial rejection,
 invalid acknowledgement, queue drop or failure throws `HueExportError`; its
-`report` contains cumulative accepted/rejected/failed/pending counts. Accepted
+`report` contains cumulative accepted/rejected/failed counts and current pending gauges. Accepted
 means the collector acknowledged receipt, not that a complete trace has arrived.
 A malformed response reports uncertain acceptance as failure. Partial successes
 are not retried. Warning-only acknowledgements with zero rejected records remain
@@ -210,9 +363,25 @@ HTTP `status`. Missing expected spans and required fields remain explicit; a 200
 response alone is not success. A successful result verifies those requested
 conditions only. Use Hue's UI to inspect captured values and redaction.
 
+## Dependencies
+
+The tracing core depends only on official `@opentelemetry/*` packages. The optional
+`@hue-run/sdk/evals` entry point uses `zod` for its bounded runtime contracts; install that peer
+when you use evaluations or simulations. JSON Schema scoring also uses `ajv`, an optional peer
+loaded inside a worker only when `builtins.jsonSchema` scores a case; without it that scorer
+reports `SchemaValidatorUnavailable`. Install it when you use that scorer:
+
+```bash
+npm install zod
+# Add ajv too when using builtins.jsonSchema.
+npm install ajv
+```
+
+See [THIRD_PARTY_NOTICES.md](https://github.com/hue-run/hue-sdk/blob/main/THIRD_PARTY_NOTICES.md) for licenses.
+
 ## Package verification
 
-From the repository root with Node 24 and Bun 1.3.9 on PATH:
+From the repository root with Node 24 and Bun 1.4.2 on PATH:
 
 ```sh
 node packages/sdk-typescript/scripts/verify-package.mjs
@@ -224,7 +393,7 @@ HTTP exporter suite against that installed package, and installs/builds the
 standalone reference chatbot. It prints the artifact paths. No package is
 published. The chatbot README describes running that external installation.
 
-# Local evaluation workflows
+## Local evaluation workflows
 
 The optional `@hue-run/sdk/evals` entry point supports dataset/scorer registration, frozen-version experiments, local built-in/custom scoring, upload resume, and historical rescoring. See the [evaluation guide](https://docs.hue.run/evaluations/first-evaluation) for the complete journey, content policy and checkpoint recovery contract.
 
@@ -241,10 +410,16 @@ export const POST = createManagedTargetHandler({
   // Application-owned functions: keep your current provider, tools and tracing.
   target: async ({ input, config, inputFiles, signal }) =>
     runAgentForEvaluation({ input, config, inputFiles, signal }),
+  tracer: hue.tracer, // Required with a Hue-owned client: Hue never registers a global tracer.
   flushTelemetry: () => hue.flush(), // Existing Hue client; flush traces and logs.
 });
 ```
 
+Without `tracer`, the handler falls back to the global OpenTelemetry tracer, its span is not
+recorded, and every invocation returns `uncertain`. An application that only uses `createHue()`
+also needs an OpenTelemetry context manager installed for the handler's span to propagate; see
+the [managed-run guide](https://docs.hue.run/evaluations/managed-runs).
+
 `runAgentForEvaluation` adapts your application result to `{ output, files? }`.
 Files contain `filename`, `contentType`, actual `Uint8Array` data and an optional
 `primary` flag. The helper verifies input bytes, claims the invocation, saves the
@@ -253,5 +428,13 @@ Use a 120-second host request limit for the default 90-second execution and
 30-second finalization budget; your target must honor `signal`.
 
 See the [managed-run guide](https://docs.hue.run/evaluations/managed-runs) and the
-[full adapter contract](MANAGED_TARGETS.md) for registration, file handling,
+[full adapter contract](https://github.com/hue-run/hue-sdk/blob/main/packages/sdk-typescript/MANAGED_TARGETS.md) for registration, file handling,
 existing-provider flush callbacks and recovery. Local/CI runners remain available.
+
+## 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.
+
+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. 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 safety](https://docs.hue.run/guides/production-safety).
+
+Queued records snapshot supported telemetry values when a span ends or a log is emitted; later caller mutations cannot change queued data. Resource attributes still awaiting detection are omitted with a sanitized warning. Later records include them after detection finishes; await resource detection before instrumentation when those attributes are required.

package/dist/ai-sdk.d.ts

@@ -1,4 +1,12 @@
 import type { TelemetryOptions } from "ai";
 import type { HueClient } from "./client.js";
-/** Use as the call's telemetry option; it does not change global AI SDK integrations. */
+/**
+ * Per-call telemetry for AI SDK 7: pass as an agent's or generation call's `telemetry` option.
+ * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session/user
+ * identifiers; prompt and response recording follow `captureContent`. It does not change global
+ * AI SDK integrations.
+ *
+ * @throws TypeError when the client is enabled and the installed `ai` major version is below 7;
+ * AI SDK 6 applications use `hueExperimentalTelemetry` from `@hue-run/sdk` instead.
+ */
 export declare function hueTelemetry(hue: HueClient): TelemetryOptions;

package/dist/ai-sdk.js

@@ -1,8 +1,43 @@
+import { createRequire } from "node:module";
 import { OpenTelemetry } from "@ai-sdk/otel";
-/** Use as the call's telemetry option; it does not change global AI SDK integrations. */
+let installedAiMajor;
+/**
+ * The installed `ai` major version, read once per process. An unreadable or unparsable version
+ * is left to the peer dependency range rather than rejected here.
+ */
+function aiMajor() {
+    if (installedAiMajor === undefined) {
+        let major = Number.NaN;
+        try {
+            const manifest = createRequire(import.meta.url)("ai/package.json");
+            major = Number(String(manifest.version).split(".")[0]);
+        }
+        catch {
+            /* The peer range decides. */
+        }
+        installedAiMajor = Number.isInteger(major) ? major : Number.NaN;
+    }
+    return Number.isNaN(installedAiMajor) ? undefined : installedAiMajor;
+}
+/**
+ * Per-call telemetry for AI SDK 7: pass as an agent's or generation call's `telemetry` option.
+ * Spans come from Hue's tracer, so they parent under `withSpan` and inherit session/user
+ * identifiers; prompt and response recording follow `captureContent`. It does not change global
+ * AI SDK integrations.
+ *
+ * @throws TypeError when the client is enabled and the installed `ai` major version is below 7;
+ * AI SDK 6 applications use `hueExperimentalTelemetry` from `@hue-run/sdk` instead.
+ */
 export function hueTelemetry(hue) {
+    // Core tracing also installs beside AI SDK 6. This adapter needs the v7 per-call
+    // integration API, so fail explicitly during configuration instead of silently on v6.
+    if (hue.enabled) {
+        const major = aiMajor();
+        if (major !== undefined && major < 7)
+            throw new TypeError("hueTelemetry requires ai@7 or later; AI SDK 6 applications pass hueExperimentalTelemetry(hue) from @hue-run/sdk as experimental_telemetry");
+    }
     return {
-        isEnabled: true,
+        isEnabled: hue.enabled,
         recordInputs: hue.captureContent,
         recordOutputs: hue.captureContent,
         integrations: [new OpenTelemetry({ tracer: hue.tracer, usage: true })],