@hue-run/sdk 0.1.2 → 0.1.4

package/MANAGED_TARGETS.md

@@ -0,0 +1,84 @@
+# Run an existing agent from Hue
+
+`@hue-run/sdk/managed` adapts an existing server-side function to Hue's managed
+evaluation protocol. Hue dispatches a frozen case; your application keeps its
+model, tools and OpenTelemetry provider. This helper does not create an agent,
+choose a model, install instrumentation or replace global providers.
+
+```ts
+import { createManagedTargetHandler } from "@hue-run/sdk/managed";
+
+// Your application initializes its existing NodeSDK/context manager before requests.
+export const POST = createManagedTargetHandler({
+  machineCredential: process.env.HUE_MANAGED_TARGET_SECRET!,
+  // baseUrl defaults to https://app.hue.run; configure it here, never from a request.
+  target: async ({ input, config, inputFiles, signal }) => {
+    const result = await existingAgent({ input, config, files: inputFiles, signal });
+    return {
+      output: { text: result.text },
+      files: result.files.map((file) => ({
+        filename: file.name,
+        contentType: file.contentType,
+        data: file.bytes, // Uint8Array; upload these exact bytes once generated.
+        primary: file.isPrimary,
+      })),
+    };
+  },
+  flushTelemetry: async () => {
+    await flushExistingTracesAndLogs(); // Throw if either pipeline did not flush.
+  },
+});
+```
+
+The example's `existingAgent` and `flushExistingTracesAndLogs` are application
+functions. A flush callback must throw on delivery failure; an explicit `false`
+result or a Hue report with pending records also leaves telemetry pending. Hue's
+flush API throws for new export failures; its historical failure counters do not
+invalidate later successful drains. An optional `tracer` uses an already configured provider. The default
+uses the global provider, which must record the supplied sampled trace context.
+Configure a host request limit of at least 120 seconds for the defaults: 90 seconds
+for the target and 30 seconds reserved for uploads, checkpointing and telemetry.
+Targets must honor `signal`; JavaScript cannot forcibly stop a callback that
+ignores cancellation. A callback still running at the deadline returns `uncertain`.
+
+## What the helper guarantees
+
+- Validates the dedicated machine credential before network access. The scoped
+  `X-Hue-Invocation-Token` is used only for Hue callbacks; neither credential is
+  passed to the target, output uploads or telemetry attributes.
+- Claims the assigned execution before calling the target. A duplicate claim
+  returns HTTP 409 without another agent call. A lost claim response is uncertain.
+- Downloads only declared files from the configured Hue origin and verifies their
+  length and SHA-256 before calling the target. No redirects are followed.
+- Creates a real `ai.managed_target` span under the incoming W3C `traceparent`,
+  using the existing provider. It records no input/output content of its own.
+- Uploads returned file buffers, including valid secondary files on an error
+  result. Each reservation has a stable idempotency key; an already ready file is
+  reused. Only granted content-type/private-access upload headers are accepted.
+- Ends the span, checkpoints the outcome, flushes existing traces and logs, then
+  persists a telemetry acknowledgement before returning HTTP 200.
+
+HTTP 200 returns `{protocolVersion:1,executionId,state:"checkpointed",telemetry}`.
+`telemetry` is `"flushed"` or `"pending"`; a flush/acknowledgement failure preserves
+the saved outcome. A checkpoint is not experiment completion or a receipt proving
+all evidence has been stored. Hue performs that independent verification.
+
+The callback returns `ManagedTargetResult`: optional `output` JSON, `state`
+(`succeeded`, `error`, `cancelled`), a safe `{type,message?}` error, file buffers and
+optional token usage. Omitted output means unavailable; `null` is present output.
+At most one file can be primary. Files are limited to 16, 25 MiB each and 64 MiB
+total; input/output JSON and HTTP envelopes also have bounded sizes. Error text
+is caller-owned public content: never return raw provider exceptions or secrets.
+
+Signed file PUTs make one attempt and never follow redirects. If their acknowledgement
+is lost, Hue's completion callback verifies the stored bytes before accepting the file.
+Only identical idempotent reservation/completion/checkpoint/telemetry callbacks retry,
+at most once within the finalization deadline. The helper never retries the agent, automatically
+resumes a lost callback, or claims exactly-once execution across crashes. After
+transport loss or a callback deadline, inspect the saved execution in Hue. An
+explicitly authorized new attempt is a separate execution decision.
+
+Protect and rate-limit the endpoint at your host as appropriate. Keep the dedicated
+machine credential server-side. This API uses invocation-scoped callbacks, not the
+project-wide `EvaluationClient` credential. The existing telemetry pipeline retains
+its configured content-capture policy and exporter credentials.

package/README.md

@@ -177,6 +177,39 @@ drain, including records emitted before its call. Stop request production
 before shutdown so late spans cannot race it. A client does not own instrumented
 operations still running in the application.
 
+## Verify a stored application trace
+
+After exercising a real application request and finishing its stream, flush the
+providers that own its spans, then verify their OpenTelemetry IDs:
+
+```ts
+// traceId and requestSpanId come from the application request you just exercised.
+await hue.flush(); // borrowed providers must also finish their own work
+const result = await hue.verifyTrace(traceId, {
+  expectedSpanIds: [requestSpanId], // include known model/tool span IDs when available
+  requiredFields: ["input", "output", "model"], // choose fields this request should emit
+});
+if (!result.verified) throw new Error("Trace verification timed out; inspect missing spans and fields.");
+console.log(result.receipt?.traceUrl);
+```
+
+Available in TypeScript `0.1.3`. `verifyTrace` makes a read-only, project-key-authenticated
+receipt request. It does not flush, run your application, create a test span, or
+read captured values. `fields` reports the presence of stored normalized input,
+output, model, usage, and session data across the trace; it does not establish
+content correctness or that every possible span has arrived. Leave unknown usage
+and intentionally disabled content out of `requiredFields`.
+
+The default budget is 10 seconds; set `timeoutMillis` up to 60,000. Only a recognized
+missing trace, HTTP 429, or HTTP 503 is retried, respecting `Retry-After` and the
+overall deadline. Incomplete evidence is also checked again within that deadline.
+A timeout returns `{ verified: false, receipt }`, retaining the latest observed
+receipt or `null`. Authentication, unsupported endpoint, transport, and invalid
+response failures throw `HueTraceVerificationError` with a safe `code` and optional
+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.
+
 ## Package verification
 
 From the repository root with Node 24 and Bun 1.3.9 on PATH:
@@ -194,3 +227,31 @@ published. The chatbot README describes running that external installation.
 # 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.
+
+## Managed targets
+
+Start a frozen dataset run in Hue while your agent stays in your application. Expose a
+protected POST route around your existing function:
+
+```ts
+import { createManagedTargetHandler } from "@hue-run/sdk/managed";
+
+export const POST = createManagedTargetHandler({
+  machineCredential: process.env.HUE_MANAGED_TARGET_SECRET!,
+  // Application-owned functions: keep your current provider, tools and tracing.
+  target: async ({ input, config, inputFiles, signal }) =>
+    runAgentForEvaluation({ input, config, inputFiles, signal }),
+  flushTelemetry: () => hue.flush(), // Existing Hue client; flush traces and logs.
+});
+```
+
+`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
+outcome and correlates its span with Hue. It never retries the agent automatically.
+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,
+existing-provider flush callbacks and recovery. Local/CI runners remain available.

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type Context, type Span, type Tracer } from "@opentelemetry/api";
 import { HueTransport } from "./transport.js";
-import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, JsonValue, ProjectConnection, SpanOptions } from "./types.js";
+import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, JsonValue, ProjectConnection, SpanOptions, VerifyTraceOptions, TraceVerification } from "./types.js";
 export interface ExistingHueProviders {
     transport: HueTransport;
     tracerProvider: FlushableTracerProvider;
@@ -23,6 +23,7 @@ export declare class HueClient {
     private shutdownPromise?;
     private flushPromise?;
     constructor(options: HueOptions | ExistingHueProviders);
+    verifyTrace(traceId: string, options?: VerifyTraceOptions): Promise<TraceVerification>;
     getContext(): Context;
     withSpan<T>(name: string, callback: (span: HueSpan) => Promise<T> | T, options?: SpanOptions): Promise<T>;
     tool<T extends JsonValue | undefined>(name: string, input: JsonValue, execute: () => Promise<T> | T): Promise<T>;

package/dist/client.js

@@ -6,6 +6,7 @@ import { TracerProvider } from "@opentelemetry/sdk-trace";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MAX_CONTENT_BYTES } from "./config.js";
 import { createHueTransport, HueExportError } from "./transport.js";
+import { verifyTrace } from "./receipt.js";
 export class HueConnectionError extends Error {
     status;
     constructor(message, status) {
@@ -97,8 +98,11 @@ export class HueClient {
             this.loggerProvider = logger;
         }
         this.captureContent = this.transport.options.captureContent;
-        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", "0.1.2"), this.storage);
-        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", "0.1.2");
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", "0.1.4"), this.storage);
+        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", "0.1.4");
+    }
+    verifyTrace(traceId, options = {}) {
+        return verifyTrace(this.transport.options, traceId, options);
     }
     getContext() {
         return this.storage.getStore()?.context ?? context.active();

package/dist/evals/json.js

@@ -55,6 +55,7 @@ export function sourceDigest(source) {
 }
 export function uuid(value) {
     if (typeof value !== "string" ||
+        value.length !== 36 ||
         !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value))
         throw new TypeError("Expected a UUID");
     return value;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { createHue, HueClient, HueConnectionError, type ExistingHueProviders } from "./client.js";
 export { createHueTransport, HueTransport, HueExportError } from "./transport.js";
+export { HueTraceVerificationError } from "./receipt.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createHue, HueClient, HueConnectionError } from "./client.js";
 export { createHueTransport, HueTransport, HueExportError } from "./transport.js";
+export { HueTraceVerificationError } from "./receipt.js";

package/dist/managed.d.ts

@@ -0,0 +1,65 @@
+import { type Tracer } from "@opentelemetry/api";
+import type { JsonValue } from "./types.js";
+export interface ManagedInputFile {
+    artifactId: string;
+    filename: string;
+    contentType: string;
+    byteSize: number;
+    sha256: string;
+    role: string;
+}
+export interface ManagedInvocation {
+    protocolVersion: 1;
+    executionId: string;
+    attempt: number;
+    input: JsonValue;
+    config: JsonValue;
+    inputFiles: ManagedInputFile[];
+    deadline: string;
+    traceparent: string;
+}
+export interface ManagedTargetContext {
+    executionId: string;
+    attempt: number;
+    input: JsonValue;
+    config: JsonValue;
+    inputFiles: Array<ManagedInputFile & {
+        data: Uint8Array;
+    }>;
+    signal: AbortSignal;
+    traceId: string;
+}
+export interface ManagedOutputFile {
+    filename: string;
+    contentType: string;
+    data: Uint8Array;
+    primary?: boolean;
+}
+export interface ManagedTargetResult {
+    state?: "succeeded" | "error" | "cancelled";
+    output?: JsonValue;
+    /** Public, safe error summary. Never include provider errors, credentials or stacks. */
+    error?: {
+        type: string;
+        message?: string;
+    };
+    files?: ManagedOutputFile[];
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+export interface ManagedTargetOptions {
+    machineCredential: string;
+    baseUrl?: string;
+    target: (invocation: ManagedTargetContext) => Promise<ManagedTargetResult>;
+    /** Flush the application's existing trace AND log pipelines; do not shut them down. */
+    flushTelemetry: () => Promise<unknown>;
+    tracer?: Tracer;
+    /** Reserve finalization time inside the host's request limit. Default 90 seconds. */
+    maxExecutionMillis?: number;
+    /** Upload/checkpoint/flush grace after execution deadline, at most 30 seconds. */
+    finalizationMillis?: number;
+}
+/** A machine-authenticated, framework-neutral POST handler. Never retries the target. */
+export declare function createManagedTargetHandler(options: ManagedTargetOptions): (request: Request) => Promise<Response>;

package/dist/managed.js

@@ -0,0 +1,537 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { context, ROOT_CONTEXT, SpanStatusCode, trace } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { validateOptions } from "./config.js";
+import { json, uuid } from "./evals/json.js";
+const MIB = 1024 * 1024;
+const MAX_FILE = 25 * MIB;
+const MAX_TOTAL = 64 * MIB;
+const STATES = new Set([
+    "queued",
+    "dispatched",
+    "running",
+    "uncertain",
+    "checkpointed",
+    "completed",
+    "unsupported",
+    "error",
+    "cancelled",
+    "superseded",
+]);
+const propagator = new W3CTraceContextPropagator();
+/** A machine-authenticated, framework-neutral POST handler. Never retries the target. */
+export function createManagedTargetHandler(options) {
+    token(options.machineCredential);
+    const baseUrl = validateOptions({
+        apiKey: "managed-invocation",
+        serviceName: "managed-target",
+        captureContent: false,
+        baseUrl: options.baseUrl,
+    }).baseUrl;
+    const maxExecution = bounded(options.maxExecutionMillis ?? 90_000, 1, 90_000);
+    const grace = bounded(options.finalizationMillis ?? 30_000, 1, 30_000);
+    if (typeof options.target !== "function" || typeof options.flushTelemetry !== "function")
+        throw new TypeError("target and flushTelemetry are required");
+    const credential = createHash("sha256").update(`Bearer ${options.machineCredential}`).digest();
+    return async (request) => {
+        if (request.method !== "POST")
+            return reply(405, { error: "method_not_allowed" });
+        const supplied = request.headers.get("authorization") ?? "";
+        if (supplied.length > 8192 ||
+            !timingSafeEqual(credential, createHash("sha256").update(supplied).digest()))
+            return reply(401, { error: "authentication" });
+        const began = Date.now();
+        let invocation;
+        let invocationToken;
+        try {
+            invocationToken = token(request.headers.get("x-hue-invocation-token"));
+            const body = await readBytes(request, MIB, AbortSignal.timeout(5_000));
+            invocation = validateInvocation(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body)));
+            if (Date.parse(invocation.deadline) <= Date.now())
+                return reply(408, { error: "deadline_exceeded" });
+        }
+        catch {
+            return reply(400, { error: "invalid_invocation" });
+        }
+        const executionEnd = Math.min(Date.parse(invocation.deadline), began + maxExecution);
+        const finalEnd = Math.min(executionEnd + grace, began + maxExecution + grace);
+        const signal = AbortSignal.timeout(Math.max(1, executionEnd - Date.now()));
+        const api = new InvocationApi(baseUrl, invocationToken, invocation.executionId);
+        const uncertain = () => reply(503, { protocolVersion: 1, executionId: invocation.executionId, state: "uncertain" });
+        let claim;
+        try {
+            claim = object(await api.json("POST", "/claim", {}, executionEnd));
+            if (typeof claim.claimed !== "boolean" ||
+                claim.executionId !== invocation.executionId ||
+                !STATES.has(String(claim.state)))
+                throw new Error();
+        }
+        catch {
+            return uncertain();
+        }
+        if (!claim.claimed)
+            return reply(409, {
+                protocolVersion: 1,
+                executionId: invocation.executionId,
+                state: claim.state,
+            });
+        // The application's existing provider owns this span and every child. No global setup.
+        const parent = propagator.extract(ROOT_CONTEXT, { traceparent: invocation.traceparent }, {
+            keys: (carrier) => Object.keys(carrier),
+            get: (carrier, key) => carrier[key],
+        });
+        const span = (options.tracer ?? trace.getTracer("@hue-run/sdk/managed")).startSpan("ai.managed_target", {
+            attributes: {
+                "hue.execution.id": invocation.executionId,
+                "hue.execution.attempt": invocation.attempt,
+            },
+        }, parent);
+        const spanContext = span.spanContext();
+        if (!span.isRecording() || spanContext.traceId !== invocation.traceparent.split("-")[1]) {
+            span.end();
+            return uncertain();
+        }
+        let result;
+        try {
+            const inputFiles = [];
+            for (const file of invocation.inputFiles) {
+                const data = await api.bytes(`/inputs/${file.artifactId}`, file.byteSize, executionEnd);
+                if (data.byteLength !== file.byteSize || sha256(data) !== file.sha256)
+                    throw new Error("input_integrity");
+                inputFiles.push({ ...file, data });
+            }
+            // Synchronous input hashing or a busy event loop can exhaust the budget
+            // before the abort timer runs. Do not start a paid callback in that gap.
+            if (Date.now() >= executionEnd)
+                throw new Error("deadline");
+            signal.throwIfAborted();
+            result = await within(context.with(trace.setSpan(parent, span), () => options.target({
+                executionId: invocation.executionId,
+                attempt: invocation.attempt,
+                input: invocation.input,
+                config: invocation.config,
+                inputFiles,
+                signal,
+                traceId: spanContext.traceId,
+            })), signal);
+            validateResult(result);
+        }
+        catch {
+            // A timed-out callback may still be running. Do not claim a terminal outcome for it.
+            if (signal.aborted || Date.now() >= executionEnd) {
+                span.setStatus({ code: SpanStatusCode.ERROR });
+                span.end();
+                return uncertain();
+            }
+            result = {
+                state: "error",
+                error: { type: "target_error", message: "The target or input validation failed." },
+            };
+        }
+        const artifactIds = [];
+        let primaryArtifactId;
+        let uploadFailed = false;
+        for (const [index, file] of (result.files ?? []).entries()) {
+            try {
+                const hash = sha256(file.data);
+                const reserved = object(await api.json("POST", "/files", {
+                    idempotencyKey: `file:${index}:${hash}`,
+                    filename: file.filename,
+                    contentType: file.contentType,
+                    byteSize: file.data.byteLength,
+                    sha256: hash,
+                }, finalEnd, true));
+                const artifactId = uuid(reserved.artifactId);
+                if (reserved.state !== "ready") {
+                    const uploadUrl = safeUploadUrl(reserved.uploadUrl);
+                    const headers = uploadHeaders(reserved.headers, file.contentType);
+                    // Never replay a signed write. Completion independently verifies the
+                    // stored hash, so it can settle a lost successful acknowledgement.
+                    try {
+                        await api.upload(uploadUrl, file.data, headers, finalEnd);
+                    }
+                    catch {
+                        /* Verify below. */
+                    }
+                    await api.json("POST", `/files/${artifactId}/complete`, {}, finalEnd, true);
+                }
+                artifactIds.push(artifactId);
+                if (file.primary)
+                    primaryArtifactId = artifactId;
+            }
+            catch {
+                uploadFailed = true;
+            }
+        }
+        // Preserve every successfully uploaded secondary even when another file failed.
+        if (uploadFailed)
+            result = {
+                ...result,
+                state: "error",
+                error: {
+                    type: "artifact_upload_failed",
+                    message: "One or more output files could not be stored.",
+                },
+            };
+        const state = result.state ?? "succeeded";
+        if (state !== "succeeded")
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        span.end();
+        const outcome = {
+            protocolVersion: 1,
+            executionId: invocation.executionId,
+            state,
+            ...(Object.hasOwn(result, "output") ? { output: result.output } : {}),
+            ...(result.error ? { error: result.error } : {}),
+            artifactIds,
+            ...(primaryArtifactId ? { primaryArtifactId } : {}),
+            traceId: spanContext.traceId,
+            expectedSpanIds: [spanContext.spanId],
+            ...(result.usage ? { usage: result.usage } : {}),
+        };
+        try {
+            await api.json("POST", "/outcome", outcome, finalEnd, true);
+        }
+        catch {
+            return uncertain();
+        }
+        const acknowledgement = {
+            protocolVersion: 1,
+            executionId: invocation.executionId,
+            state: "checkpointed",
+        };
+        try {
+            const remaining = finalEnd - Date.now();
+            if (remaining <= 0)
+                throw new Error();
+            const flushed = await within(Promise.resolve().then(options.flushTelemetry), AbortSignal.timeout(remaining));
+            if (flushed === false)
+                throw new Error("flush_failed");
+            if (flushed &&
+                typeof flushed === "object" &&
+                ("pendingSpans" in flushed || "pendingLogs" in flushed)) {
+                // Hue's failure counters are cumulative; its flush throws for new failures.
+                // Pending counters describe the current drain and must both be zero.
+                const report = flushed;
+                if (report.pendingSpans !== 0 || report.pendingLogs !== 0)
+                    throw new Error("flush_pending");
+            }
+            await api.json("POST", "/telemetry", { expectedSpanIds: [spanContext.spanId], flushed: true }, finalEnd, true);
+        }
+        catch {
+            return reply(200, { ...acknowledgement, telemetry: "pending" });
+        }
+        return reply(200, { ...acknowledgement, telemetry: "flushed" });
+    };
+}
+class InvocationApi {
+    baseUrl;
+    invocationToken;
+    executionId;
+    constructor(baseUrl, invocationToken, executionId) {
+        this.baseUrl = baseUrl;
+        this.invocationToken = invocationToken;
+        this.executionId = executionId;
+    }
+    url(path) {
+        return `${this.baseUrl}/api/v1/managed-executions/${this.executionId}${path}`;
+    }
+    async json(method, path, value, deadline, retry = false) {
+        const body = JSON.stringify(json(value, MIB));
+        const bytes = await this.request(this.url(path), {
+            method,
+            headers: {
+                authorization: `Bearer ${this.invocationToken}`,
+                "content-type": "application/json",
+            },
+            body,
+        }, MIB, deadline, retry);
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    bytes(path, maximum, deadline) {
+        return this.request(this.url(path), { headers: { authorization: `Bearer ${this.invocationToken}` } }, maximum, deadline, false);
+    }
+    async upload(url, data, headers, deadline) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error("deadline");
+        const signal = AbortSignal.timeout(remaining);
+        await new Promise((resolve, reject) => {
+            let activeResponse;
+            const finish = (error) => {
+                signal.removeEventListener("abort", abort);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const abort = () => {
+                activeResponse?.destroy();
+                request.destroy();
+                finish(new Error("Hue managed upload failed"));
+            };
+            // Signed writes must not be replayed by fetch, redirect handling or a
+            // reused-socket retry. A lost response is settled by Hue's verified read.
+            const request = (new URL(url).protocol === "https:" ? httpsRequest : httpRequest)(url, {
+                method: "PUT",
+                agent: false,
+                signal,
+                maxHeaderSize: 16 * 1024,
+                headers: { ...headers, "content-length": String(data.byteLength) },
+            }, (response) => {
+                activeResponse = response;
+                if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+                    response.destroy();
+                    finish(new Error("Hue managed upload failed"));
+                    return;
+                }
+                void (async () => {
+                    let length = 0;
+                    for await (const chunk of response) {
+                        signal.throwIfAborted();
+                        length += Buffer.byteLength(chunk);
+                        if (length > MIB)
+                            throw new Error("Upload response too large");
+                    }
+                    signal.throwIfAborted();
+                    finish();
+                })().catch(() => {
+                    response.destroy();
+                    finish(new Error("Hue managed upload failed"));
+                });
+            });
+            request.once("error", () => finish(new Error("Hue managed upload failed")));
+            signal.addEventListener("abort", abort, { once: true });
+            request.end(Buffer.from(data));
+        });
+    }
+    async request(url, init, maximum, deadline, retry) {
+        for (let attempt = 0;; attempt++) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new Error("deadline");
+            try {
+                const signal = AbortSignal.timeout(remaining);
+                const response = await fetch(url, { ...init, redirect: "error", signal });
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    if (![429, 500, 502, 503, 504].includes(response.status))
+                        throw new PermanentError();
+                    throw new Error();
+                }
+                return await readBytes(response, maximum, signal);
+            }
+            catch (error) {
+                if (!retry ||
+                    attempt >= 1 ||
+                    error instanceof PermanentError ||
+                    Date.now() + 100 >= deadline)
+                    throw new Error("Hue managed request failed");
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        }
+    }
+}
+class PermanentError extends Error {
+}
+function reply(status, body) {
+    return Response.json(body, { status, headers: { "cache-control": "no-store" } });
+}
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function token(value) {
+    if (typeof value !== "string" || !value || value.length > 8192 || /[\s\u0000]/u.test(value))
+        throw new TypeError("Invalid credential");
+    return value;
+}
+function bounded(value, minimum, maximum) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < minimum ||
+        value > maximum)
+        throw new TypeError("Invalid integer");
+    return value;
+}
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError("Expected object");
+    return value;
+}
+function filename(value) {
+    if (typeof value !== "string" ||
+        !value.trim() ||
+        value.length > 255 ||
+        /[\x00-\x1f\x7f/\\]/u.test(value) ||
+        value === "." ||
+        value === "..")
+        throw new TypeError("Invalid filename");
+    return value;
+}
+function shortString(value, maximum = 255) {
+    if (typeof value !== "string" ||
+        !value ||
+        value.length > maximum ||
+        /[\x00-\x1f\x7f]/u.test(value))
+        throw new TypeError("Invalid string");
+    return value;
+}
+function validateInvocation(value) {
+    const v = object(json(value, MIB));
+    if (Object.keys(v).some((key) => ![
+        "protocolVersion",
+        "executionId",
+        "attempt",
+        "input",
+        "config",
+        "inputFiles",
+        "deadline",
+        "traceparent",
+    ].includes(key)))
+        throw new TypeError("Unknown invocation field");
+    if (v.protocolVersion !== 1 || !Object.hasOwn(v, "input") || !Object.hasOwn(v, "config"))
+        throw new TypeError("Invalid protocol");
+    uuid(v.executionId);
+    bounded(v.attempt, 1, Number.MAX_SAFE_INTEGER);
+    if (typeof v.deadline !== "string" ||
+        v.deadline.trim() !== v.deadline ||
+        !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(v.deadline) ||
+        !Number.isFinite(Date.parse(v.deadline)))
+        throw new TypeError("Invalid deadline");
+    if (typeof v.traceparent !== "string" ||
+        v.traceparent.length !== 55 ||
+        !/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/.test(v.traceparent) ||
+        /^00-0{32}-/.test(v.traceparent) ||
+        /-0{16}-01$/.test(v.traceparent))
+        throw new TypeError("A sampled W3C traceparent is required");
+    if (!Array.isArray(v.inputFiles) || v.inputFiles.length > 16)
+        throw new TypeError("Invalid files");
+    let total = 0;
+    const ids = new Set();
+    for (const raw of v.inputFiles) {
+        const file = object(raw);
+        const id = uuid(file.artifactId);
+        if (Object.keys(file).some((key) => !["artifactId", "filename", "contentType", "byteSize", "sha256", "role"].includes(key)))
+            throw new TypeError("Unknown file field");
+        if (ids.has(id))
+            throw new TypeError("Duplicate input file");
+        ids.add(id);
+        filename(file.filename);
+        shortString(file.contentType);
+        shortString(file.role, 64);
+        total += bounded(file.byteSize, 0, MAX_FILE);
+        if (typeof file.sha256 !== "string" ||
+            file.sha256.length !== 64 ||
+            !/^[0-9a-f]{64}$/.test(file.sha256))
+            throw new TypeError("Invalid hash");
+    }
+    if (total > MAX_TOTAL)
+        throw new TypeError("Input files too large");
+    return v;
+}
+function validateResult(result) {
+    object(result);
+    if (result.state && !["succeeded", "error", "cancelled"].includes(result.state))
+        throw new TypeError("Invalid outcome");
+    if (Object.hasOwn(result, "output"))
+        json(result.output);
+    if (result.error) {
+        shortString(result.error.type, 64);
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(result.error.type))
+            throw new TypeError("Invalid error type");
+        if (result.error.message !== undefined)
+            shortString(result.error.message, 1000);
+    }
+    if (result.usage)
+        for (const count of Object.values(result.usage))
+            bounded(count, 0, Number.MAX_SAFE_INTEGER);
+    if (result.files !== undefined && (!Array.isArray(result.files) || result.files.length > 16))
+        throw new TypeError("Invalid files");
+    let total = 0;
+    let primary = 0;
+    for (const file of result.files ?? []) {
+        filename(file.filename);
+        shortString(file.contentType);
+        if (!(file.data instanceof Uint8Array))
+            throw new TypeError("File data must be bytes");
+        total += bounded(file.data.byteLength, 0, MAX_FILE);
+        if (file.primary !== undefined && typeof file.primary !== "boolean")
+            throw new TypeError("Invalid primary");
+        if (file.primary)
+            primary++;
+    }
+    if (total > MAX_TOTAL || primary > 1)
+        throw new TypeError("Invalid output files");
+}
+function safeUploadUrl(value) {
+    if (typeof value !== "string" || value.length > 8192 || /[\x00-\x20\x7f]/u.test(value))
+        throw new TypeError("Invalid upload URL");
+    const url = new URL(value);
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+        url.username ||
+        url.password ||
+        url.hash)
+        throw new TypeError("Invalid upload URL");
+    // Validate without rewriting the provider's signed capability.
+    return value;
+}
+function uploadHeaders(value, contentType) {
+    const headers = { "content-type": contentType };
+    if (value === undefined || value === null)
+        return headers;
+    for (const [name, raw] of Object.entries(object(value))) {
+        const lower = name.toLowerCase();
+        const value = shortString(raw);
+        if (lower === "content-type" && value === contentType)
+            headers[lower] = value;
+        else if (lower === "x-vercel-blob-access" && value === "private")
+            headers[lower] = value;
+        else
+            throw new TypeError("Unsupported upload header");
+    }
+    return headers;
+}
+async function within(promise, signal) {
+    signal.throwIfAborted();
+    let abort;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                abort = () => reject(new Error("Deadline exceeded"));
+                signal.addEventListener("abort", abort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+async function readBytes(source, maximum, signal) {
+    const declared = source.headers.get("content-length");
+    if (declared !== null && (!/^\d+$/.test(declared) || Number(declared) > maximum))
+        throw new Error("Oversized body");
+    if (!source.body)
+        return new Uint8Array();
+    const reader = source.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const next = await within(reader.read(), signal);
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > maximum)
+                throw new Error("Oversized body");
+            chunks.push(next.value);
+        }
+        return Buffer.concat(chunks, size);
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+}

package/dist/receipt.d.ts

@@ -0,0 +1,10 @@
+import type { HueOptions, TraceVerification, VerifyTraceOptions } from "./types.js";
+export declare class HueTraceVerificationError extends Error {
+    readonly code: "authentication" | "http" | "invalid_response" | "transport";
+    readonly status?: number | undefined;
+    constructor(code: "authentication" | "http" | "invalid_response" | "transport", message: string, status?: number | undefined);
+}
+/** Observe persisted evidence after the application and its exporter have finished. */
+export declare function verifyTrace(connection: Pick<HueOptions, "apiKey"> & {
+    baseUrl: string;
+}, traceId: string, options?: VerifyTraceOptions): Promise<TraceVerification>;

package/dist/receipt.js

@@ -0,0 +1,207 @@
+const fields = ["input", "output", "model", "usage", "session"];
+const MAX_RESPONSE_BYTES = 64 * 1024;
+export class HueTraceVerificationError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "HueTraceVerificationError";
+    }
+}
+function invalidResponse() {
+    throw new HueTraceVerificationError("invalid_response", "Hue returned an invalid trace receipt. Check the server and SDK versions.");
+}
+function validId(value, length) {
+    return (typeof value === "string" &&
+        value.length === length &&
+        new RegExp(`^[0-9a-f]{${length}}$`).test(value) &&
+        !/^0+$/.test(value));
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseReceipt(value, traceId, expected, origin) {
+    if (!record(value) ||
+        value.traceId !== traceId ||
+        !Number.isSafeInteger(value.spanCount) ||
+        value.spanCount < 0 ||
+        !Number.isSafeInteger(value.revision) ||
+        value.revision < 0 ||
+        !record(value.fields) ||
+        fields.some((field) => typeof value.fields[field] !== "boolean") ||
+        typeof value.traceUrl !== "string" ||
+        value.traceUrl.length > 2048)
+        invalidResponse();
+    let traceUrl;
+    try {
+        traceUrl = new URL(value.traceUrl);
+    }
+    catch {
+        invalidResponse();
+    }
+    if (traceUrl.origin !== origin || traceUrl.username || traceUrl.password)
+        invalidResponse();
+    const matched = value.matchedSpanIds, missing = value.missingSpanIds;
+    if (!Array.isArray(matched) ||
+        !Array.isArray(missing) ||
+        matched.length + missing.length !== expected.length ||
+        [...matched, ...missing].some((id) => !validId(id, 16) || !expected.includes(id)) ||
+        new Set([...matched, ...missing]).size !== expected.length ||
+        matched.length > value.spanCount)
+        invalidResponse();
+    // Return only the documented fields, never arbitrary response content.
+    return {
+        traceId,
+        spanCount: value.spanCount,
+        revision: value.revision,
+        fields: Object.fromEntries(fields.map((field) => [field, value.fields[field]])),
+        matchedSpanIds: expected.filter((id) => matched.includes(id)),
+        missingSpanIds: expected.filter((id) => missing.includes(id)),
+        traceUrl: traceUrl.href,
+    };
+}
+async function readJson(response) {
+    const length = response.headers.get("content-length");
+    if (length && /^\d+$/.test(length) && Number(length) > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel();
+        invalidResponse();
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        invalidResponse();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                invalidResponse();
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        invalidResponse();
+    }
+}
+function retryDelay(value) {
+    if (!value)
+        return 0;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+async function pause(milliseconds, signal) {
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
+/** Observe persisted evidence after the application and its exporter have finished. */
+export async function verifyTrace(connection, traceId, options = {}) {
+    if (!validId(traceId, 32))
+        throw new TypeError("traceId must be a nonzero lowercase 32-character OpenTelemetry trace ID");
+    if (options === null || typeof options !== "object" || Array.isArray(options))
+        throw new TypeError("Trace verification options must be an object");
+    const expected = options.expectedSpanIds === undefined ? [] : options.expectedSpanIds;
+    if (!Array.isArray(expected) ||
+        expected.length > 100 ||
+        expected.some((id) => !validId(id, 16)) ||
+        new Set(expected).size !== expected.length)
+        throw new TypeError("expectedSpanIds must contain at most 100 unique nonzero lowercase 16-character span IDs");
+    const required = options.requiredFields === undefined ? [] : options.requiredFields;
+    if (!Array.isArray(required) ||
+        required.some((field) => !fields.includes(field)) ||
+        new Set(required).size !== required.length)
+        throw new TypeError("requiredFields must contain unique receipt field names: input, output, model, usage, session");
+    const timeout = options.timeoutMillis === undefined ? 10_000 : options.timeoutMillis;
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 60_000)
+        throw new TypeError("timeoutMillis must be greater than zero and at most 60000");
+    // Snapshot caller arrays so concurrent mutation cannot alter the verification criteria.
+    const expectedIds = [...expected], requiredFields = [...required];
+    const url = new URL(`/api/v1/traces/${traceId}/receipt`, connection.baseUrl);
+    for (const id of expectedIds)
+        url.searchParams.append("expectedSpanId", id);
+    const controller = new AbortController();
+    const deadline = performance.now() + timeout;
+    const timer = setTimeout(() => controller.abort(), timeout);
+    let receipt = null;
+    let delay = 250;
+    try {
+        while (!controller.signal.aborted && performance.now() < deadline) {
+            const response = await fetch(url, {
+                headers: { Authorization: `Bearer ${connection.apiKey}`, Accept: "application/json" },
+                redirect: "manual",
+                credentials: "omit",
+                cache: "no-store",
+                signal: controller.signal,
+            });
+            let retryAfter = 0;
+            if (response.status === 200) {
+                receipt = parseReceipt(await readJson(response), traceId, expectedIds, url.origin);
+                if (!controller.signal.aborted &&
+                    performance.now() < deadline &&
+                    receipt.missingSpanIds.length === 0 &&
+                    requiredFields.every((field) => receipt.fields[field]))
+                    return { verified: true, receipt };
+            }
+            else if (response.status === 404) {
+                const body = await readJson(response);
+                if (!record(body) || body.code !== "TRACE_NOT_FOUND")
+                    throw new HueTraceVerificationError("http", "This Hue server does not support trace receipts. Check the server version and baseUrl.", 404);
+            }
+            else {
+                await response.body?.cancel();
+                if (response.status === 429 || response.status === 503) {
+                    retryAfter = retryDelay(response.headers.get("retry-after"));
+                }
+                else if (response.status === 401 || response.status === 403) {
+                    throw new HueTraceVerificationError("authentication", "Hue denied trace verification. Check the project key, its access, and expiration.", response.status);
+                }
+                else {
+                    throw new HueTraceVerificationError("http", "Hue refused trace verification. Check the server version and configured origin; redirects are not followed.", response.status);
+                }
+            }
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                break;
+            const wait = Math.max(delay, retryAfter);
+            await pause(Math.min(wait, remaining), controller.signal);
+            // A truncated backoff exhausts this call even if a timer wakes just early.
+            if (wait >= remaining)
+                break;
+            delay = Math.min(delay * 2, 1000);
+        }
+    }
+    catch (error) {
+        if (!controller.signal.aborted && performance.now() < deadline) {
+            if (error instanceof HueTraceVerificationError)
+                throw error;
+            throw new HueTraceVerificationError("transport", "Hue trace verification could not reach the server. Check the network and configured origin.");
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { verified: false, receipt };
+}

package/dist/types.d.ts

@@ -61,3 +61,24 @@ export interface ProjectConnection {
     organizationId: string;
     slug: string;
 }
+export type TraceReceiptField = "input" | "output" | "model" | "usage" | "session";
+export interface TraceReceipt {
+    traceId: string;
+    spanCount: number;
+    revision: number;
+    /** Presence of stored normalized fields; not a judgment of content correctness. */
+    fields: Record<TraceReceiptField, boolean>;
+    matchedSpanIds: string[];
+    missingSpanIds: string[];
+    traceUrl: string;
+}
+export interface VerifyTraceOptions {
+    expectedSpanIds?: string[];
+    requiredFields?: TraceReceiptField[];
+    /** Total request/retry budget, including response bodies. Default 10000; maximum 60000. */
+    timeoutMillis?: number;
+}
+export interface TraceVerification {
+    verified: boolean;
+    receipt: TraceReceipt | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -19,6 +19,7 @@
     "dist",
     "README.md",
     "EVALUATIONS.md",
+    "MANAGED_TARGETS.md",
     "LICENSE"
   ],
   "type": "module",
@@ -34,6 +35,10 @@
     "./evals": {
       "types": "./dist/evals.d.ts",
       "import": "./dist/evals.js"
+    },
+    "./managed": {
+      "types": "./dist/managed.d.ts",
+      "import": "./dist/managed.js"
     }
   },
   "scripts": {