@uncoil.dev/sdk 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# Uncoil TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Observability and tracing for AI agents. Gain full visibility into your agent's decision-making process, tool usage, and LLM costs.
+
+Uncoil records each agent run as one trace: every model call, tool call, retry, failure and cost. It also ingests OpenTelemetry. Free plan available. Docs: [uncoil.dev/docs](https://www.uncoil.dev/docs). New to agent observability? Read the [complete guide](https://www.uncoil.dev/blog/ai-agent-observability-complete-guide).
+
+## Installation
+
+```bash
+npm install @uncoil.dev/sdk
+# or
+yarn add @uncoil.dev/sdk
+```
+
+## Quickstart
+
+1. Get your API Key from the [Uncoil Dashboard](https://www.uncoil.dev).
+2. Set it as an environment variable:
+
+```bash
+export UNCOIL_API_KEY=your_sk_live_...
+```
+
+3. Instrument your agent:
+
+```typescript
+import { traceAgent, llmCall, toolCall } from '@uncoil.dev/sdk';
+
+const agent = traceAgent(async (query: string) => {
+  // LLM Call
+  await llmCall({
+    input: query,
+    output: "Thinking...",
+    modelId: "gpt-4o",
+    costUsd: 0.002,
+    latencyMs: 800
+  });
+  
+  // Tool Use
+  await toolCall({
+    toolName: "web_search",
+    input: { q: query },
+    output: "Found results...",
+    latencyMs: 1200
+  });
+  
+  return "Final Answer";
+}, { environment: "development", release: "quickstart" });
+```
+
+## Steps
+
+Inside a `traceAgent` function, every step you record is linked to the step it ran in, so the trace graph
+shows which step called which and how loops repeat. Use `span` for a block and `observe` for a function:
+
+```ts
+import { observe, span, traceAgent } from "@uncoil.dev/sdk";
+
+const searchDocs = observe(async function searchDocs(query: string) {
+  return search(query);
+}, { type: "tool" });
+
+export const answer = traceAgent(async (question: string) => {
+  for (let turn = 0; turn < 5; turn++) {
+    const reply = await span("think", () =>
+      span("chat", async (step) => {
+        const reply = await callModel(question);
+        step.set({ model: "claude-sonnet-5-5", inputTokens: reply.usage.input, outputTokens: reply.usage.output });
+        return reply;
+      }, { type: "llm", input: question }),
+    { type: "agent" });
+    if (reply.done) return reply.text;
+    await searchDocs(reply.query);
+  }
+});
+```
+
+`type` is one of `agent`, `llm`, `tool`, `retrieval` or `span`. Errors are recorded with their type and
+message. Concurrent runs stay in separate traces (Node's AsyncLocalStorage). Inputs and outputs have obvious
+secrets (bearer tokens, API keys, JWTs, `password=` values) removed and are capped at 10,000 characters;
+avoid sending anything else you would not want stored.
+
+## Features
+
+- **traceAgent Wrapper:** Automatically captures run lifecycle and errors.
+- **Granular Spans:** Manually record LLMs, tools, and custom decisions.
+- **Environment Aware:** Automatically picks up API keys from `process.env`.
+- **Lightweight:** Minimal dependencies, optimized for Node.js and Edge runtimes.
+- **Session context:** Add `sessionId`, `endUserId`, `environment`, `release`, and `tags` to connect related traces.
+
+## Feedback and evaluation scores
+
+Pass `projectId` when constructing the client to attach end-user feedback and typed scores to traces:
+
+```typescript
+const client = new UncoilClient({ apiKey: process.env.UNCOIL_API_KEY, projectId: "your-project-id" });
+client.feedback(runId, true, { kind: "thumb", comment: "Helpful answer" });
+client.score(runId, "answer_quality", 0.92, { dataType: "numeric" });
+```
+
+These helpers use the project API key, deduplicate when given a `dedupeKey`, and never throw into the agent process.
+
+## Prompt deployment
+
+Resolve a deployed prompt without shipping a new application build:
+
+```typescript
+const deployed = await client.getPrompt("support-agent", "production");
+await client.ingest({ spanType: "llm", input: question, output, promptVersionId: deployed.version.id });
+```
+
+Prompt responses are cached for 60 seconds by default. Pass `{ cacheTtlMs: 0, fallback }` for development or guaranteed-availability behavior.
+
+## License
+
+MIT
+
+## Provider integrations (0.4.0)
+
+Wrap an existing client once. Its normal calls, typed results, streaming chunks and errors keep working.
+Provider packages are optional; install the providers you use. Node.js is required (async context propagation).
+
+```ts
+import OpenAI from "openai";
+import Anthropic from "@anthropic-ai/sdk";
+import { wrapOpenAI, wrapAnthropic, UncoilLangGraphHandler, traceAgent } from "@uncoil.dev/sdk";
+
+const openai = wrapOpenAI(new OpenAI());
+const anthropic = wrapAnthropic(new Anthropic());
+// Existing calls now record model, input/output, latency, tokens, TTFT and provider errors.
+const reply = await openai.responses.create({ model: process.env.OPENAI_MODEL!, input: "Hello" });
+const stream = await anthropic.messages.create({
+  model: process.env.ANTHROPIC_MODEL!, max_tokens: 100,
+  messages: [{ role: "user", content: "Hello" }], stream: true,
+});
+for await (const event of stream) { /* existing handling */ }
+
+// For LangGraph, pass one reusable handler in the graph invocation config.
+await graph.invoke(input, { callbacks: [new UncoilLangGraphHandler()] });
+```
+
+Use `UNCOIL_API_KEY` and the existing region/host configuration. Pass `{ client }` for a custom
+`UncoilClient`. Calls inside `traceAgent`/`span` inherit the current run and parent; standalone provider
+calls get a completed root, so unrelated requests never share an `unknown` run. LangGraph callbacks
+record graph/node/tool/model parent relationships. Use either framework model callbacks or a wrapped
+provider for each model call to avoid recording that call twice.
+
+Supported APIs: OpenAI `chat.completions.create`, `responses.create`, and their `.stream()` helpers;
+Anthropic `messages.create`, `messages.stream`, and beta messages equivalents. Async iteration and
+helper event/final-result APIs are observed. OpenAI `.withResponse()` retains headers/request IDs;
+`.asResponse()` remains unparsed and records request timing only. Stream conversion helpers such as
+`.tee()` and `.toReadableStream()` are passed through and do not observe consumption: iterate the
+wrapped stream for complete usage/TTFT. Explicit `stream_options.include_usage: false` is respected.
+Cancel/abort records partial output once; telemetry failure never replaces the provider's result or error.
+
+Payloads use the SDK's existing redaction and size caps. Disable capture with
+`{ captureInput: false, captureOutput: false }`. Provider usage is stored exactly as returned, including
+cache breakdown in metadata. **Prices are not guessed:** cost defaults to zero with
+`metadata.costKnown=false`. Supply `calculateCost({provider, model, inputTokens, outputTokens, usage})`
+using your own current rate card to record USD cost. Missing provider usage remains unknown, not an
+estimated token count. None of these wrappers publishes your key or changes provider billing.
+
+Anthropic total input tokens include uncached input plus cache reads and cache writes; the original
+usage breakdown remains in metadata for rate-card calculations. See the [provider’s token breakdown](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
+
+## Framework one-liners
+
+Quickest start: call `init()` once at startup and every OpenAI and Anthropic call is traced, with no client wrapping (`UNCOIL_API_KEY` is read from the environment).
+
+```ts
+import { init } from "@uncoil.dev/sdk";
+init();
+```
+
+`init()` patches the installed `openai` and `@anthropic-ai/sdk` (both the CommonJS and ES-module builds; `await init().ready` if your first call happens instantly). Call the function it returns to switch it off. Use it or the per-framework options below for the same calls, not both. LangChain / LangGraph need `callbacks: [new UncoilLangGraphHandler()]`, and the Vercel AI SDK needs the middleware shown here.
+
+```ts
+import { wrapLanguageModel } from "ai";
+import { uncoilMiddleware, traceTools } from "@uncoil.dev/sdk";
+
+const model = wrapLanguageModel({ model: openai("gpt-4o"), middleware: uncoilMiddleware() }); // Vercel AI SDK
+const tools = traceTools({ searchDocs, sendEmail });   // any functions or { execute } tool objects
+```
+
+OpenAI (`wrapOpenAI`), Anthropic (`wrapAnthropic`) and LangGraph (`UncoilLangGraphHandler`) work as before. Copy-paste starters live in [`templates/`](./templates).
+
+## Sampling, redaction and clearer errors
+
+```ts
+const uncoil = new UncoilClient({
+  sampleRate: 0.1,                 // record about 1 in 10 runs; each run is kept or dropped whole
+  redact: { patterns: [/ACME-\d{6}/] },   // emails, phones and card numbers are masked by default; add your own patterns
+  onError: (error) => log(error.message),            // problems come with a plain-language fix (error.hint)
+});
+```
+
+Spans that report an error are kept even when their run was not sampled (`keepErrors: false` turns that off). Secrets such as bearer tokens and API keys are always removed, and emails, phone numbers and card numbers are masked before anything leaves your app. To send them as they are, set `redact: { pii: false }`.
+
+### Sign in from the terminal
+
+```bash
+npx @uncoil.dev/sdk login
+```
+
+Opens your browser so you can sign in (or create a free account), pick or create a project, and confirm the code shown in your terminal. The key is then saved to `.env.local` as `UNCOIL_API_KEY`, with `UNCOIL_PROJECT_ID` next to it (and `UNCOIL_REGION` for the US region). In a git repo the file is added to `.gitignore` if it is not already ignored. The key travels encrypted to your machine and is never printed. Options: `--region eu|us`, `--new <name>` (create a project with this name), `--no-browser` (only print the address and code), `--env-file <path>` and `--json`. Picking a project that already sends data replaces its key, and the browser asks you to confirm that first. Plain Node does not read `.env.local` by itself; run `node --env-file=.env.local app.js` or load it with dotenv.
+
+`npx @uncoil.dev/sdk doctor` also reads `.env.local`/`.env`, and now tells you which project traces will land in (`Traces will land in: <name>`). It fails if `UNCOIL_PROJECT_ID` points at a different project than the key.
+
+## Setup checker
+
+Not seeing traces? One command checks your key, region and network, then sends a test trace:
+
+```bash
+npx @uncoil.dev/sdk doctor
+```
+
+It reads `UNCOIL_API_KEY` (and `UNCOIL_REGION` / `UNCOIL_HOST` if set), tells you in plain words what is wrong and how to fix it, and exits with code 1 if anything fails. Options: `--key`, `--region eu|us`, `--host`, `--no-send` (skip the test trace) and `--json`. You can also call `runDoctor()` from code. The test trace is named "Uncoil setup check" and tagged `uncoil-doctor`; it counts as one trace on your plan.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const doctor_1 = require("./doctor");
+const login_1 = require("./login");
+const HELP = `Usage: uncoil login [options]
+       uncoil doctor [options]
+
+login   Sign in through your browser and save the API key for this folder.
+doctor  Check your API key, region and network, then send one test trace.
+
+login options:
+  --region <eu|us>    Data region (default: UNCOIL_REGION, else eu)
+  --new <name>        Create a new project with this name
+  --no-browser        Only print the address and code; do not open a browser
+  --env-file <path>   Where to save the key (default: .env.local)
+  --host <url>        Custom host (default: UNCOIL_HOST)
+  --json              Print machine-readable lines
+
+doctor options:
+
+  --key <key>       API key (default: UNCOIL_API_KEY)
+  --region <eu|us>  Data region (default: UNCOIL_REGION, else from the key)
+  --host <url>      Custom host (default: UNCOIL_HOST)
+  --no-send         Skip the test trace
+  --json            Print the result as JSON
+  -h, --help        Show this help
+
+Exit code is 0 when everything passes, 1 when a check fails.`;
+async function main(argv) {
+    const command = argv[0] === "login" || argv[0] === "doctor" ? argv[0] : "doctor";
+    const args = argv[0] === "login" || argv[0] === "doctor" ? argv.slice(1) : argv;
+    const options = {};
+    let json = false;
+    let newProject;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const value = () => {
+            const next = args[++i];
+            if (!next) {
+                console.error(`Missing value for ${arg}.\n\n${HELP}`);
+                process.exit(2);
+            }
+            return next;
+        };
+        if (arg === "-h" || arg === "--help") {
+            console.log(HELP);
+            return 0;
+        }
+        else if (arg === "--key" && command === "doctor")
+            options.apiKey = value();
+        else if (arg === "--region") {
+            const region = value().toLowerCase();
+            if (region !== "eu" && region !== "us") {
+                console.error('--region must be "eu" or "us".');
+                return 2;
+            }
+            options.region = region;
+        }
+        else if (arg === "--host")
+            options.host = value();
+        else if (arg === "--no-send" && command === "doctor")
+            options.send = false;
+        else if (arg === "--new" && command === "login")
+            newProject = value();
+        else if (arg === "--no-browser" && command === "login")
+            options.browser = false;
+        else if (arg === "--env-file" && command === "login")
+            options.envFile = value();
+        else if (arg === "--json")
+            json = true;
+        else {
+            console.error(`Unknown option ${arg}.\n\n${HELP}`);
+            return 2;
+        }
+    }
+    if (command === "login") {
+        const result = await (0, login_1.runLogin)({ ...options, newProject, json });
+        if (!result.ok)
+            console.error(json ? JSON.stringify({ event: "error", message: result.message }) : result.message);
+        return result.ok ? 0 : 1;
+    }
+    (0, login_1.loadUncoilEnv)(process.cwd());
+    const report = await (0, doctor_1.runDoctor)(options);
+    console.log(json ? JSON.stringify(report, null, 2) : (0, doctor_1.formatReport)(report));
+    return report.ok ? 0 : 1;
+}
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/dist/doctor.d.ts

@@ -0,0 +1,33 @@
+import { type UncoilRegion } from "./index";
+export type DoctorStatus = "ok" | "warn" | "fail" | "skip";
+export interface DoctorCheck {
+    id: "runtime" | "key" | "region" | "network" | "project" | "trace";
+    title: string;
+    status: DoctorStatus;
+    message: string;
+    /** Plain-language fix, present when the check did not pass. */
+    hint?: string;
+}
+export interface DoctorOptions {
+    apiKey?: string;
+    region?: UncoilRegion;
+    host?: string;
+    /** Skip the test trace; only check the key shape, region and network. */
+    send?: boolean;
+    /** Project the key is expected to belong to. Defaults to UNCOIL_PROJECT_ID. */
+    projectId?: string;
+    /** Seconds before a request is given up on. Defaults to 10. */
+    timeoutMs?: number;
+}
+export interface DoctorReport {
+    ok: boolean;
+    host: string;
+    checks: DoctorCheck[];
+    /** Set when the test trace was accepted. Search for it in your dashboard. */
+    runId?: string;
+}
+/** Shows enough of a key to recognise it without leaking it. */
+export declare function maskKey(apiKey: string): string;
+/** Runs every setup check in order and never throws. */
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+export declare function formatReport(report: DoctorReport): string;

package/dist/doctor.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskKey = maskKey;
+exports.runDoctor = runDoctor;
+exports.formatReport = formatReport;
+const index_1 = require("./index");
+function keyRegion(apiKey) {
+    if (/^(uncoil|tracify)_sk_live_eu_/.test(apiKey))
+        return "eu";
+    if (/^(uncoil|tracify)_sk_live_us_/.test(apiKey))
+        return "us";
+    if (/^(uncoil|tracify)_sk_live_/.test(apiKey))
+        return "eu";
+    return undefined;
+}
+/** Shows enough of a key to recognise it without leaking it. */
+function maskKey(apiKey) {
+    if (apiKey.length <= 12)
+        return "***";
+    return `${apiKey.slice(0, 16)}…${apiKey.slice(-4)}`;
+}
+function id() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+}
+function errorText(error) {
+    const err = error;
+    if (err?.name === "TimeoutError" || err?.name === "AbortError")
+        return "the request timed out";
+    return err?.cause?.code || err?.cause?.message || err?.message || String(error);
+}
+/** Runs every setup check in order and never throws. */
+async function runDoctor(options = {}) {
+    const checks = [];
+    const add = (check) => { checks.push(check); return check; };
+    const timeoutMs = options.timeoutMs ?? 10000;
+    const apiKey = (options.apiKey || (process.env.UNCOIL_API_KEY ?? process.env.TRACIFY_API_KEY) || "").trim();
+    const envRegion = (process.env.UNCOIL_REGION ?? process.env.TRACIFY_REGION)?.trim().toLowerCase();
+    const wanted = (options.region || (envRegion === "eu" || envRegion === "us" ? envRegion : undefined));
+    const found = keyRegion(apiKey);
+    const host = (options.host || (process.env.UNCOIL_HOST ?? process.env.TRACIFY_HOST) || index_1.UNCOIL_REGION_HOSTS[wanted ?? found ?? "eu"]).replace(/\/$/, "");
+    const report = () => ({ ok: !checks.some((c) => c.status === "fail"), host, checks, runId });
+    let runId;
+    const nodeMajor = Number(process.versions?.node?.split(".")[0]);
+    if (typeof fetch !== "function" || nodeMajor < 18) {
+        add({ id: "runtime", title: "Runtime", status: "fail", message: `This runtime has no built-in fetch (Node ${process.versions?.node ?? "unknown"}).`, hint: "Use Node 18 or newer." });
+        return report();
+    }
+    add({ id: "runtime", title: "Runtime", status: "ok", message: `Node ${process.versions.node}` });
+    if (!apiKey) {
+        add({ id: "key", title: "API key", status: "fail", message: "No API key was found.", hint: "Set the UNCOIL_API_KEY environment variable, or run with --key. Create a key on the API keys page of your dashboard." });
+        return report();
+    }
+    if (!/^(uncoil|tracify)_sk_/.test(apiKey)) {
+        add({ id: "key", title: "API key", status: "fail", message: `${maskKey(apiKey)} does not look like an Uncoil key (they start with uncoil_sk_).`, hint: "Copy the key again from the API keys page; make sure no other service's key was pasted by mistake." });
+        return report();
+    }
+    add({ id: "key", title: "API key", status: "ok", message: `Found ${maskKey(apiKey)}` });
+    try {
+        new URL(host);
+    }
+    catch {
+        add({ id: "region", title: "Region and host", status: "fail", message: `The host "${host}" is not a valid web address.`, hint: 'Use a full address such as "https://eu.cloud.uncoil.dev", or drop the host option and use --region eu or us.' });
+        return report();
+    }
+    const hostRegion = (Object.entries(index_1.UNCOIL_REGION_HOSTS).find(([, value]) => value === host)?.[0]);
+    if (found && hostRegion && found !== hostRegion) {
+        add({ id: "region", title: "Region and host", status: "fail", message: `This key belongs to ${found.toUpperCase()}, but you are pointing at ${hostRegion.toUpperCase()}.`, hint: `Set UNCOIL_REGION=${found} (or run with --region ${found}), or create a key in the ${hostRegion.toUpperCase()} region.` });
+        return report();
+    }
+    add({ id: "region", title: "Region and host", status: "ok", message: hostRegion ? `${hostRegion.toUpperCase()} · ${host}` : `Custom host · ${host}` });
+    const proxyNote = process.env.HTTPS_PROXY || process.env.https_proxy ? " A proxy is set in your environment, and Node's fetch does not use it automatically; allow this host or route the request through your proxy." : "";
+    try {
+        const response = await fetch(host, { method: "GET", redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+        add({ id: "network", title: "Network", status: "ok", message: `Reached ${host} (HTTP ${response.status}).` });
+    }
+    catch (error) {
+        add({ id: "network", title: "Network", status: "fail", message: `Could not reach ${host} (${errorText(error)}).`, hint: `Check your internet connection, firewall and the host setting.${proxyNote}` });
+        return report();
+    }
+    // Which project does this key send to? Older servers have no such route, so anything unexpected is skipped quietly.
+    const expectedProject = (options.projectId || (process.env.UNCOIL_PROJECT_ID ?? process.env.TRACIFY_PROJECT_ID) || "").trim();
+    try {
+        const response = await fetch(`${host}/api/sdk/whoami`, { headers: { Authorization: `Bearer ${apiKey}` }, signal: AbortSignal.timeout(timeoutMs) });
+        const data = response.ok ? await response.json() : null;
+        if (data?.projectId) {
+            if (expectedProject && expectedProject !== data.projectId) {
+                add({ id: "project", title: "Project", status: "fail", message: `UNCOIL_PROJECT_ID points at a different project than this key ("${data.projectName ?? data.projectId}").`, hint: "Run `npx @uncoil.dev/sdk login` in this folder again so the key and project are saved together." });
+                return report();
+            }
+            add({ id: "project", title: "Project", status: "ok", message: `Traces will land in: ${data.projectName ?? data.projectId}` });
+        }
+    }
+    catch { /* the trace check below reports connection problems */ }
+    if (options.send === false) {
+        add({ id: "trace", title: "Test trace", status: "skip", message: "Skipped (--no-send)." });
+        return report();
+    }
+    const spanRunId = `doctor_${id()}`;
+    const started = Date.now();
+    const span = {
+        spanId: `doctor_span_${id()}`,
+        runId: spanRunId,
+        traceName: "Uncoil setup check",
+        spanType: "llm_call",
+        modelId: "uncoil-doctor",
+        createdAt: new Date(started).toISOString(),
+        latencyMs: 1,
+        input: "Setup check from uncoil doctor",
+        output: "If you can see this trace in your dashboard, the SDK is set up correctly.",
+        tags: ["uncoil-doctor"],
+        metadata: { source: "uncoil doctor", sdk: "ts" },
+    };
+    try {
+        const response = await fetch(`${host}/api/ingest`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify(span),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const status = response.status;
+        if (response.ok) {
+            runId = spanRunId;
+            add({ id: "trace", title: "Test trace", status: "ok", message: `Accepted. Look for "Uncoil setup check" (run ${spanRunId}) in your dashboard.` });
+        }
+        else if (status === 401) {
+            add({ id: "trace", title: "Test trace", status: "fail", message: "Uncoil rejected the API key (401).", hint: "The key is wrong, was revoked, or belongs to another region. Create a fresh one on the API keys page." });
+        }
+        else if (status === 403) {
+            add({ id: "trace", title: "Test trace", status: "fail", message: "This key is not allowed to send data (403).", hint: "Check that the key belongs to the project you expect and has not been disabled." });
+        }
+        else if (status === 402 || status === 429) {
+            add({ id: "trace", title: "Test trace", status: "fail", message: `Uncoil is not taking data right now (${status}).`, hint: "You may be over your plan's limit or sending too fast. Check usage on the billing page, then try again." });
+        }
+        else if (status >= 500) {
+            add({ id: "trace", title: "Test trace", status: "fail", message: `Uncoil had a problem on its side (${status}).`, hint: "Your app is not affected. Check the status page and try again in a minute." });
+        }
+        else {
+            add({ id: "trace", title: "Test trace", status: "fail", message: `Uncoil did not accept the test trace (${status}).`, hint: "Update uncoil to the latest version; if it still happens, contact support." });
+        }
+    }
+    catch (error) {
+        add({ id: "trace", title: "Test trace", status: "fail", message: `The test trace could not be sent (${errorText(error)}).`, hint: `Check your connection and try again.${proxyNote}` });
+    }
+    return report();
+}
+const MARKS = { ok: "✓", warn: "!", fail: "✗", skip: "-" };
+function formatReport(report) {
+    const lines = ["Uncoil setup check", ""];
+    for (const check of report.checks) {
+        lines.push(`${MARKS[check.status]} ${check.title}: ${check.message}`);
+        if (check.hint && check.status !== "ok")
+            lines.push(`    Fix: ${check.hint}`);
+    }
+    lines.push("", report.ok ? "All good. Your setup is ready to send traces." : "Something needs fixing; see the Fix lines above.");
+    return lines.join("\n");
+}