@telemetry-dev/sdk 0.1.10 → 0.1.11

package/README.md

@@ -111,6 +111,69 @@ The default is parent-based always-on. Session roots keep the configured root po
 Nested spans and explicitly parented spans keep the real parent's policy.
 The SDK installs the [session sampling wrapper](https://github.com/telemetry-dev/telemetry/blob/main/packages/otel/README.md#correlation-attributes) on its provider. This includes the global provider that Eve uses.
 
+## Prompts
+
+`getPrompt` fetches a prompt that you manage in telemetry.dev. Fetch it by its label, so that you
+deploy a version when you move the label, without a change to the code:
+
+```ts
+import OpenAI from "openai";
+import { getPrompt, init, withPrompt } from "@telemetry-dev/sdk";
+import { wrapOpenAI } from "@telemetry-dev/openai";
+
+init();
+const openai = wrapOpenAI(new OpenAI());
+
+const prompt = await getPrompt("support/reply", { label: "production" });
+const messages = prompt.compile({ customer_message, tone });
+
+const response = await withPrompt(prompt, () =>
+  openai.chat.completions.create({ model: prompt.model?.name ?? "gpt-4o", messages }),
+);
+
+// Pin one version, as in a test:
+const pinned = await getPrompt("support/reply", { version: 13 });
+```
+
+- Without `label` and `version`, getPrompt fetches the `production` label. A text prompt needs
+  `type: "text"`; getPrompt rejects a prompt of the other type.
+- `compile(variables)` puts the values in place of `{{name}}`. A missing value becomes an empty
+  text, and a value that is not a string becomes JSON. In a chat prompt, a placeholder message
+  becomes the list of messages in its variable. A text prompt compiles to a string.
+- The prompt also has `model`, `parameters`, `tools`, and `responseFormat` of its version.
+- getPrompt keeps each prompt. When the copy is older than `cacheTtlSeconds` (default 60), a call
+  returns it at once and fetches a new copy in the background. Only a call with no copy waits for a
+  fetch, for 10 seconds at most. Calls for the same prompt share one fetch.
+- If a fetch fails, getPrompt returns the last copy that it fetched and reports the error through
+  `onError`. With no copy, it returns the `fallback` option (`version` is `null` and `isFallback`
+  is `true`). With no fallback, it rejects with a `PromptError` whose `code` tells why, for
+  example `prompt_not_found`, `label_not_found`, `insufficient_scope`, `missing_api_key`, or
+  `timeout`. A response with a different status and no API error gives `http_<status>`, for
+  example `http_302` for a redirect. getPrompt does not send the request to the location of a
+  redirect, thus your key does not go to a different host. With no copy, the calls of the next 10
+  seconds (or the TTL, if it is shorter) get the same result without a fetch. This is the one SDK
+  function that can reject: your app cannot run without its prompt.
+- getPrompt uses the API key and base URL of an enabled `init()`, or `TELEMETRY_DEV_API_KEY` and
+  `TELEMETRY_DEV_BASE_URL`, or its own `apiKey`, `baseUrl`, and `fetch` options. It reads the same
+  host that telemetry goes to, `https://ingest.telemetry.dev` by default. The key needs the read
+  scope for prompts.
+- When a label sends part of the traffic to a second version, each session keeps one version: the
+  choice uses the session id of `propagateAttributes` (or of `sessionMode: "process"`). Without a
+  session id, each call chooses at random.
+
+`withPrompt(prompt, fn)` records the prompt on each model call that starts inside `fn`:
+`td.prompt.name`, `td.prompt.version`, and `td.prompt.label` (only for a prompt fetched by label).
+When input capture is on, `td.prompt.variables` holds the JSON of the variables of the last
+`compile()` of that prompt object before `withPrompt` starts, or of the last `compile()` inside
+`fn`, after `mask` and truncation. If tasks that run at the same time share one prompt object, call
+`compile()` in `withPrompt`, or call getPrompt in each task. getPrompt returns a new object from
+the cache. If you do not, a task can record the variables of a different task. Model calls are the
+spans of type `generation` (operations `chat`, `text_completion`, and `generate_content`),
+including the spans of the provider integrations that use this SDK: OpenAI, Anthropic, Amazon
+Bedrock, Google GenAI, and OpenRouter. Spans from the AI SDK and TanStack AI integrations, and from
+other OpenTelemetry tracers, do not get the attributes. Messages from `compile()` that you pass to
+a model call outside `withPrompt` are not recorded.
+
 ## API
 
 - `init(options?)` — create the client (isolated OTel TracerProvider by default).
@@ -130,6 +193,8 @@ The SDK installs the [session sampling wrapper](https://github.com/telemetry-dev
 - `updateActiveSpan(fields)` — update the innermost active span.
 - `propagateAttributes({ userId, sessionId, metadata }, fn)` — stamps `user.id`,
   `gen_ai.conversation.id`, and `td.metadata.*` on every span and log record in scope.
+- `getPrompt(name, options?)` — fetch a prompt by label or version; see [Prompts](#prompts).
+- `withPrompt(prompt, fn)` — record the prompt on each model call in `fn`.
 - `log(message, { level, eventName, attributes }?)` — log record correlated to the active trace.
 - `getTraceparent()` — W3C traceparent of the active span (pass to other services; accept it via
   `startSpan(name, { parent })`).

package/dist/index.d.mts

@@ -16,7 +16,7 @@ type MaskFn<T = unknown> = (value: T, ctx: {
 interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
-  /** Ingest base URL. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
   baseUrl?: string;
   /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
   environment?: string;
@@ -257,4 +257,157 @@ interface ObserveOptions extends StartSpanOptions {
  */
 declare function observe<TThis, TArgs extends unknown[], TReturn>(fn: (this: TThis, ...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
 //#endregion
-export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+//#region src/prompts.d.ts
+/** A message of a chat prompt. A placeholder stands for a list of messages that the app passes. */
+type PromptMessage = {
+  readonly role: "system" | "user" | "assistant";
+  readonly content: string;
+} | {
+  readonly role: "placeholder";
+  readonly name: string;
+};
+/** A message that `compile()` makes from a prompt message. */
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+interface PromptModel {
+  readonly provider: string;
+  readonly name: string;
+}
+/** The parameters that are set in the version. A parameter that is not set is absent. */
+interface PromptParameters {
+  readonly temperature?: number;
+  readonly topP?: number;
+  readonly maxTokens?: number;
+  readonly frequencyPenalty?: number;
+  readonly presencePenalty?: number;
+  readonly stop?: readonly string[];
+  readonly seed?: number;
+  readonly toolChoice?: "auto" | "none" | "required" | {
+    readonly tool: string;
+  };
+  readonly parallelToolCalls?: boolean;
+}
+interface PromptTool {
+  readonly name: string;
+  readonly description: string;
+  /** JSON schema of the tool arguments. */
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly strict: boolean;
+}
+type PromptResponseFormat = {
+  readonly type: "text";
+} | {
+  readonly type: "json_object";
+} | {
+  readonly type: "json_schema";
+  readonly name: string;
+  readonly schema: Readonly<Record<string, unknown>>;
+  readonly strict: boolean;
+};
+/**
+ * Values for `{{name}}` variables. A missing value, null, or undefined becomes an empty text, and a
+ * value that is not a string becomes JSON. A placeholder message takes a list of messages.
+ */
+type PromptVariables<M = ChatMessage> = Readonly<Record<string, string | number | boolean | null | undefined | readonly M[]>>;
+interface PromptBase {
+  readonly name: string;
+  /** The version that the app got; null for the fallback. */
+  readonly version: number | null;
+  /** The label that the prompt was fetched by; null when it was fetched by version. */
+  readonly label: string | null;
+  /** Null for the fallback. */
+  readonly model: PromptModel | null;
+  readonly parameters: PromptParameters;
+  readonly tools: readonly PromptTool[];
+  readonly responseFormat: PromptResponseFormat;
+  /** True when getPrompt could not fetch the prompt and returned the `fallback` option. */
+  readonly isFallback: boolean;
+}
+interface ChatPrompt extends PromptBase {
+  readonly type: "chat";
+  readonly messages: readonly PromptMessage[];
+  readonly text: null;
+  /**
+   * Fills in the variables and replaces each placeholder message with the messages in its
+   * variable. `withPrompt` records the variables of the last call before it starts or inside it.
+   */
+  compile<M = ChatMessage>(variables?: PromptVariables<M>): (ChatMessage | M)[];
+}
+interface TextPrompt extends PromptBase {
+  readonly type: "text";
+  readonly messages: readonly [];
+  readonly text: string;
+  /**
+   * Fills in the variables. `withPrompt` records the variables of the last call before it starts
+   * or inside it.
+   */
+  compile(variables?: PromptVariables): string;
+}
+type Prompt = ChatPrompt | TextPrompt;
+interface GetPromptOptionsBase {
+  /** Fetch the version that this label points to. Default "production" when `version` is not set. */
+  label?: string;
+  /** Fetch this version number. Do not set it together with `label`. */
+  version?: number;
+  /** Seconds before a call fetches a kept prompt again, in the background. Default 60. */
+  cacheTtlSeconds?: number;
+  /** API key with the prompts:read scope. Falls back to the initialized client, then `TELEMETRY_DEV_API_KEY`. */
+  apiKey?: string;
+  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** Falls back to the initialized client's `fetch`, then `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+interface GetChatPromptOptions extends GetPromptOptionsBase {
+  /** Default "chat". getPrompt rejects a prompt of the other type. */
+  type?: "chat";
+  /** Messages to use when the prompt cannot be fetched and no copy of it is kept. */
+  fallback?: readonly PromptMessage[];
+}
+interface GetTextPromptOptions extends GetPromptOptionsBase {
+  type: "text";
+  /** Text to use when the prompt cannot be fetched and no copy of it is kept. */
+  fallback?: string;
+}
+type GetPromptOptions = GetChatPromptOptions | GetTextPromptOptions;
+/**
+ * Why getPrompt failed. `code` is the code of the API error (`prompt_not_found`,
+ * `label_not_found`, `insufficient_scope`, `invalid_api_key`, …), or `missing_api_key`,
+ * `timeout`, `network_error`, `invalid_response`, or `type_mismatch`. A response with a different
+ * status and no API error gives `http_<status>`, for example `http_302` for a redirect: getPrompt
+ * does not go to the location of a redirect.
+ */
+declare class PromptError extends Error {
+  readonly code: string;
+  readonly status?: number | undefined;
+  readonly name = "PromptError";
+  constructor(code: string, message: string, status?: number | undefined, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Fetches a prompt version from telemetry.dev and keeps it. When the copy is older than
+ * `cacheTtlSeconds`, a call returns it at once and fetches a new one in the background. Only a call
+ * with no copy waits for a fetch, at most 10 seconds. Calls for the same prompt share one fetch.
+ * When a fetch fails, getPrompt returns the last copy that it kept; with no copy it returns
+ * `fallback`. With neither it rejects with a `PromptError`: unlike the telemetry functions,
+ * getPrompt cannot fail open, because the app cannot run without the prompt. With no copy, the
+ * calls of the next 10 seconds (or the TTL, if it is shorter) fail the same way without a fetch.
+ *
+ * A label with a gradual rollout gives each session one version: the choice uses the session id
+ * of `propagateAttributes`, or a random choice per call without one.
+ */
+declare function getPrompt(name: string, options: GetTextPromptOptions): Promise<TextPrompt>;
+declare function getPrompt(name: string, options?: GetChatPromptOptions): Promise<ChatPrompt>;
+/**
+ * Runs `fn` with `prompt` as the prompt of each model call (generation span) that starts inside
+ * it: the spans get `td.prompt.name`, `td.prompt.version`, `td.prompt.label`, and, when input
+ * capture is on, `td.prompt.variables`. The variables are those of the last `compile()` of this
+ * prompt object before withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
+ * another task does not change them once withPrompt runs.
+ */
+declare function withPrompt<T>(prompt: Prompt, fn: () => T): T;
+//#endregion
+export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ChatMessage, type ChatPrompt, type ClientOverrides, type ExportMode, type GenerationFields, type GetChatPromptOptions, type GetPromptOptions, type GetTextPromptOptions, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type Prompt, PromptError, type PromptMessage, type PromptModel, type PromptParameters, type PromptResponseFormat, type PromptTool, type PromptVariables, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TextPrompt, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getPrompt, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext, withPrompt };

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { INVALID_SPAN_CONTEXT, ROOT_CONTEXT, SpanKind, SpanStatusCode, context, defaultTextMapGetter, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
+import { INVALID_SPAN_CONTEXT, ROOT_CONTEXT, SpanKind, SpanStatusCode, context, createContextKey, defaultTextMapGetter, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
 import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator, parseTraceParent } from "@opentelemetry/core";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
-import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createExportFailures, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
+import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createExportFailures, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, sha256, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 //#region src/config.ts
 const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
@@ -546,6 +546,303 @@ const NOOP_SPAN_HANDLE = {
 	end: () => {}
 };
 //#endregion
+//#region src/prompts.ts
+/**
+* Why getPrompt failed. `code` is the code of the API error (`prompt_not_found`,
+* `label_not_found`, `insufficient_scope`, `invalid_api_key`, …), or `missing_api_key`,
+* `timeout`, `network_error`, `invalid_response`, or `type_mismatch`. A response with a different
+* status and no API error gives `http_<status>`, for example `http_302` for a redirect: getPrompt
+* does not go to the location of a redirect.
+*/
+var PromptError = class extends Error {
+	name = "PromptError";
+	constructor(code, message, status, options) {
+		super(message, options);
+		this.code = code;
+		this.status = status;
+	}
+};
+const FETCH_TIMEOUT_MS = 1e4;
+/** How long a failed fetch with no copy answers calls, so that they do not each fetch again. */
+const ERROR_TTL_MS = 1e4;
+const MAX_CACHE_ENTRIES = 1e3;
+const VARIABLE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const MODEL_CALL_OPERATIONS = new Set([
+	"chat",
+	"text_completion",
+	"generate_content"
+]);
+const PROMPT_KEY = createContextKey("telemetry.dev prompt");
+const cache = /* @__PURE__ */ new Map();
+const compiledVariables = /* @__PURE__ */ new WeakMap();
+async function getPrompt(name, options = {}) {
+	const type = options.type ?? "chat";
+	checkOptions(name, options, type);
+	const core = currentClient().core;
+	const env = resolveEnv();
+	const apiKey = options.apiKey ?? core?.config.apiKey ?? env.TELEMETRY_DEV_API_KEY;
+	const baseUrl = (options.baseUrl || core?.config.baseUrl || env.TELEMETRY_DEV_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+	const label = options.version === void 0 ? options.label ?? "production" : null;
+	const onError = core?.config.onError;
+	let response;
+	try {
+		if (!apiKey) throw new PromptError("missing_api_key", "No API key: pass apiKey or set TELEMETRY_DEV_API_KEY");
+		const url = new URL(`${baseUrl}/v1/prompts`);
+		url.searchParams.set("name", name);
+		if (label === null) url.searchParams.set("version", String(options.version));
+		else url.searchParams.set("label", label);
+		response = await load([
+			baseUrl,
+			keyFingerprint(apiKey),
+			name,
+			label === null ? `version:${options.version}` : `label:${label}`
+		].join("\0"), (options.cacheTtlSeconds ?? 60) * 1e3, () => fetchPrompt(url, {
+			authorization: `Bearer ${apiKey}`,
+			"x-telemetry-dev-sdk": core?.config.sdkName ?? "@telemetry-dev/sdk"
+		}, options.fetch ?? core?.config.fetchImpl ?? globalThis.fetch), onError);
+	} catch (error) {
+		if (options.fallback === void 0) throw error;
+		reportError(onError, error);
+		return createPrompt({
+			name,
+			type,
+			label,
+			version: null,
+			isFallback: true,
+			content: {
+				messages: type === "chat" ? options.fallback : [],
+				text: type === "text" ? options.fallback : null,
+				model: null,
+				parameters: {},
+				tools: [],
+				responseFormat: { type: "text" }
+			}
+		});
+	}
+	if (response.type !== type) throw new PromptError("type_mismatch", `${name} is a ${response.type} prompt; pass type: "${response.type}"`);
+	const chosen = response.rollout && inRollout(response) ? response.rollout : response;
+	return createPrompt({
+		name: response.name,
+		type,
+		label: response.label,
+		version: chosen.version,
+		isFallback: false,
+		content: chosen
+	});
+}
+/**
+* Runs `fn` with `prompt` as the prompt of each model call (generation span) that starts inside
+* it: the spans get `td.prompt.name`, `td.prompt.version`, `td.prompt.label`, and, when input
+* capture is on, `td.prompt.variables`. The variables are those of the last `compile()` of this
+* prompt object before withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
+* another task does not change them once withPrompt runs.
+*/
+function withPrompt(prompt, fn) {
+	const scope = {
+		prompt,
+		variables: compiledVariables.get(prompt)
+	};
+	return withContext$1(activeContext$1().setValue(PROMPT_KEY, scope), fn);
+}
+/** The td.prompt.* attributes for a span with this operation that starts in `ctx`. */
+function promptAttributes(ctx, operation, capture) {
+	if (!MODEL_CALL_OPERATIONS.has(operation)) return void 0;
+	const scope = ctx.getValue(PROMPT_KEY) ?? activeContext$1().getValue(PROMPT_KEY);
+	if (!scope) return void 0;
+	const { prompt, variables } = scope;
+	return omitUndefined({
+		"td.prompt.name": prompt.name,
+		"td.prompt.version": prompt.version ?? void 0,
+		"td.prompt.label": prompt.label ?? void 0,
+		"td.prompt.variables": variables !== void 0 && capture.captureInput ? prepareCaptureValue("td.prompt.variables", variables, capture) : void 0
+	});
+}
+function checkOptions(name, options, type) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("name must be a non-empty string");
+	if (type !== "chat" && type !== "text") throw new TypeError("type must be \"chat\" or \"text\"");
+	if (options.label !== void 0 && options.version !== void 0) throw new TypeError("Pass label or version, not both");
+	if (options.version !== void 0 && (!Number.isSafeInteger(options.version) || options.version < 1)) throw new RangeError("version must be a positive integer");
+	const ttl = options.cacheTtlSeconds;
+	if (ttl !== void 0 && !(Number.isFinite(ttl) && ttl >= 0)) throw new RangeError("cacheTtlSeconds must be a non-negative number");
+	if (options.fallback !== void 0 && (type === "chat" ? !Array.isArray(options.fallback) : typeof options.fallback !== "string")) throw new TypeError(type === "chat" ? "fallback must be a list of messages" : "fallback must be a string");
+}
+/**
+* Returns the kept copy of a prompt, and fetches a new copy in the background when it is older
+* than the TTL. Only a call with no copy waits for a fetch. A failed fetch with no copy fails the
+* calls of the next ERROR_TTL_MS (or the TTL, if it is shorter) without a fetch.
+*/
+async function load(key, ttlMs, fetchResponse, onError) {
+	let entry = cache.get(key);
+	if (!entry) {
+		if (cache.size >= MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value);
+		entry = { checkedAt: 0 };
+		cache.set(key, entry);
+	}
+	const fresh = Date.now() < entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS));
+	if (entry.response) {
+		if (!fresh) entry.pending ??= refresh(entry, fetchResponse, onError);
+		return entry.response;
+	}
+	if (fresh) throw entry.error;
+	return entry.pending ??= refresh(entry, fetchResponse, onError);
+}
+function refresh(entry, fetchResponse, onError) {
+	return fetchResponse().then((response) => {
+		entry.response = response;
+		return response;
+	}, (error) => {
+		if (!entry.response) {
+			entry.error = error;
+			throw error;
+		}
+		reportError(onError, error);
+		return entry.response;
+	}).finally(() => {
+		entry.checkedAt = Date.now();
+		entry.pending = void 0;
+	});
+}
+async function fetchPrompt(url, headers, fetchImpl) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetchImpl(url, {
+			method: "GET",
+			headers,
+			signal: controller.signal,
+			redirect: "manual"
+		});
+		const body = await res.json().catch(() => void 0);
+		if (!res.ok) {
+			const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+			throw new PromptError(typeof error.code === "string" ? error.code : `http_${res.status}`, typeof error.message === "string" ? error.message : `telemetry.dev returned ${res.status}`, res.status);
+		}
+		const response = parseResponse(body);
+		if (!response) throw new PromptError("invalid_response", "telemetry.dev returned a prompt it cannot read");
+		return response;
+	} catch (error) {
+		if (controller.signal.aborted) throw new PromptError("timeout", `Fetching the prompt took more than ${FETCH_TIMEOUT_MS} ms`);
+		if (error instanceof PromptError) throw error;
+		throw new PromptError("network_error", "Could not reach telemetry.dev", void 0, { cause: error });
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function createPrompt(input) {
+	const { content, type } = input;
+	const prompt = Object.freeze({
+		name: input.name,
+		type,
+		version: input.version,
+		label: input.label,
+		messages: content.messages,
+		text: content.text,
+		model: content.model,
+		parameters: content.parameters,
+		tools: content.tools,
+		responseFormat: content.responseFormat,
+		isFallback: input.isFallback,
+		compile(variables = {}) {
+			compiledVariables.set(prompt, variables);
+			const scope = activeContext$1().getValue(PROMPT_KEY);
+			if (scope?.prompt === prompt) scope.variables = variables;
+			return type === "chat" ? compileMessages(content.messages, variables) : fill(content.text ?? "", variables);
+		}
+	});
+	return prompt;
+}
+function compileMessages(messages, variables) {
+	return messages.flatMap((message) => {
+		if (message.role !== "placeholder") return [{
+			role: message.role,
+			content: fill(message.content, variables)
+		}];
+		const value = Object.hasOwn(variables, message.name) ? variables[message.name] : void 0;
+		if (value == null) return [];
+		if (!Array.isArray(value)) throw new TypeError(`The ${message.name} variable must be a list of messages`);
+		return value;
+	});
+}
+function fill(text, variables) {
+	return text.replace(VARIABLE, (_tag, name) => {
+		const value = Object.hasOwn(variables, name) ? variables[name] : void 0;
+		if (value == null) return "";
+		return typeof value === "string" ? value : jsonAttr(value) ?? "";
+	});
+}
+function inRollout(response) {
+	const sessionId = sessionIdOf(activeContext$1()) ?? currentClient().core?.config.processSessionId;
+	return (sessionId === void 0 ? Math.floor(Math.random() * 100) : fnv1a(`${response.name}:${response.label}:${sessionId}`) % 100) < response.rollout.percent;
+}
+function fnv1a(text) {
+	let hash = 2166136261;
+	for (const byte of new TextEncoder().encode(text)) hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+	return hash;
+}
+function keyFingerprint(apiKey) {
+	const digest = sha256(new TextEncoder().encode(apiKey)).subarray(0, 16);
+	return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function parseResponse(body) {
+	if (!isRecord(body)) return void 0;
+	const { name, type, label, version, rollout } = body;
+	if (typeof name !== "string" || type !== "chat" && type !== "text" || label !== null && typeof label !== "string" || !isVersion(version)) return;
+	const content = parseContent(body, type);
+	if (!content) return void 0;
+	if (rollout == null) return deepFreeze({
+		name,
+		type,
+		label,
+		version,
+		...content,
+		rollout: null
+	});
+	if (!isRecord(rollout) || !isVersion(rollout.version) || !Number.isInteger(rollout.percent) || rollout.percent < 0 || rollout.percent > 100) return;
+	const rolloutContent = parseContent(rollout, type);
+	if (!rolloutContent) return void 0;
+	return deepFreeze({
+		name,
+		type,
+		label,
+		version,
+		...content,
+		rollout: {
+			percent: rollout.percent,
+			version: rollout.version,
+			...rolloutContent
+		}
+	});
+}
+function parseContent(value, type) {
+	const { messages, text, model, parameters, tools, responseFormat } = value;
+	if (!(type === "chat" ? Array.isArray(messages) && messages.every(isPromptMessage) : typeof text === "string") || !isRecord(model) || typeof model.provider !== "string" || typeof model.name !== "string" || !isRecord(parameters) || !Array.isArray(tools) || !tools.every((tool) => isRecord(tool) && typeof tool.name === "string") || !isRecord(responseFormat) || typeof responseFormat.type !== "string") return;
+	return {
+		messages: type === "chat" ? messages : [],
+		text: type === "text" ? text : null,
+		model,
+		parameters,
+		tools,
+		responseFormat
+	};
+}
+function isPromptMessage(value) {
+	if (!isRecord(value)) return false;
+	return value.role === "placeholder" ? typeof value.name === "string" : (value.role === "system" || value.role === "user" || value.role === "assistant") && typeof value.content === "string";
+}
+function isVersion(value) {
+	return Number.isSafeInteger(value) && value >= 1;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepFreeze(value) {
+	if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const item of Object.values(value)) deepFreeze(item);
+	}
+	return value;
+}
+//#endregion
 //#region src/span.ts
 const SPAN_META = /* @__PURE__ */ new WeakMap();
 const SEVERITY_ERROR = 17;
@@ -621,6 +918,7 @@ function createSpanHandle(core, name, options = {}) {
 		"gen_ai.conversation.id": sessionId
 	}), sessionId, core.config.apiKey);
 	const attrs = fieldsToAttributes(options, meta.type, meta.capture);
+	const operation = attrs["gen_ai.operation.name"] ?? SPAN_TYPE_OPERATIONS[meta.type];
 	const span = core.tracer.startSpan(name, {
 		kind: options.kind ?? SpanKind.INTERNAL,
 		startTime: options.startTime,
@@ -628,6 +926,7 @@ function createSpanHandle(core, name, options = {}) {
 		attributes: {
 			"gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type],
 			...propagatedFromContext(parentCtx),
+			...promptAttributes(parentCtx, operation, meta.capture),
 			...attrs
 		}
 	}, parentCtx);
@@ -815,4 +1114,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { PromptError, SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getPrompt, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext, withPrompt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",

package/src/config.ts

@@ -22,7 +22,7 @@ export type MaskFn<T = unknown> = (value: T, ctx: { key: string }) => T;
 export interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
-  /** Ingest base URL. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
   baseUrl?: string;
   /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
   environment?: string;

package/src/index.ts

@@ -46,6 +46,25 @@ export { log, type LogOptions } from "./logs.ts";
 
 export { observe, type ObserveOptions } from "./observe.ts";
 
+export {
+  type ChatMessage,
+  type ChatPrompt,
+  type GetChatPromptOptions,
+  getPrompt,
+  type GetPromptOptions,
+  type GetTextPromptOptions,
+  type Prompt,
+  PromptError,
+  type PromptMessage,
+  type PromptModel,
+  type PromptParameters,
+  type PromptResponseFormat,
+  type PromptTool,
+  type PromptVariables,
+  type TextPrompt,
+  withPrompt,
+} from "./prompts.ts";
+
 export {
   activeContext,
   extractW3cContext,

package/src/prompts.ts

@@ -0,0 +1,701 @@
+import { type Attributes, type Context, createContextKey } from "@opentelemetry/api";
+import {
+  activeContext,
+  DEFAULT_BASE_URL,
+  jsonAttr,
+  omitUndefined,
+  reportError,
+  resolveEnv,
+  sessionIdOf,
+  sha256,
+  withContext,
+} from "@telemetry-dev/otel";
+
+import type { FieldCaptureConfig } from "./attrs.ts";
+import { prepareCaptureValue } from "./capture.ts";
+import { currentClient } from "./client.ts";
+
+/** A message of a chat prompt. A placeholder stands for a list of messages that the app passes. */
+export type PromptMessage =
+  | { readonly role: "system" | "user" | "assistant"; readonly content: string }
+  | { readonly role: "placeholder"; readonly name: string };
+
+/** A message that `compile()` makes from a prompt message. */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface PromptModel {
+  readonly provider: string;
+  readonly name: string;
+}
+
+/** The parameters that are set in the version. A parameter that is not set is absent. */
+export interface PromptParameters {
+  readonly temperature?: number;
+  readonly topP?: number;
+  readonly maxTokens?: number;
+  readonly frequencyPenalty?: number;
+  readonly presencePenalty?: number;
+  readonly stop?: readonly string[];
+  readonly seed?: number;
+  readonly toolChoice?: "auto" | "none" | "required" | { readonly tool: string };
+  readonly parallelToolCalls?: boolean;
+}
+
+export interface PromptTool {
+  readonly name: string;
+  readonly description: string;
+  /** JSON schema of the tool arguments. */
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly strict: boolean;
+}
+
+export type PromptResponseFormat =
+  | { readonly type: "text" }
+  | { readonly type: "json_object" }
+  | {
+      readonly type: "json_schema";
+      readonly name: string;
+      readonly schema: Readonly<Record<string, unknown>>;
+      readonly strict: boolean;
+    };
+
+/**
+ * Values for `{{name}}` variables. A missing value, null, or undefined becomes an empty text, and a
+ * value that is not a string becomes JSON. A placeholder message takes a list of messages.
+ */
+export type PromptVariables<M = ChatMessage> = Readonly<
+  Record<string, string | number | boolean | null | undefined | readonly M[]>
+>;
+
+interface PromptBase {
+  readonly name: string;
+  /** The version that the app got; null for the fallback. */
+  readonly version: number | null;
+  /** The label that the prompt was fetched by; null when it was fetched by version. */
+  readonly label: string | null;
+  /** Null for the fallback. */
+  readonly model: PromptModel | null;
+  readonly parameters: PromptParameters;
+  readonly tools: readonly PromptTool[];
+  readonly responseFormat: PromptResponseFormat;
+  /** True when getPrompt could not fetch the prompt and returned the `fallback` option. */
+  readonly isFallback: boolean;
+}
+
+export interface ChatPrompt extends PromptBase {
+  readonly type: "chat";
+  readonly messages: readonly PromptMessage[];
+  readonly text: null;
+  /**
+   * Fills in the variables and replaces each placeholder message with the messages in its
+   * variable. `withPrompt` records the variables of the last call before it starts or inside it.
+   */
+  compile<M = ChatMessage>(variables?: PromptVariables<M>): (ChatMessage | M)[];
+}
+
+export interface TextPrompt extends PromptBase {
+  readonly type: "text";
+  readonly messages: readonly [];
+  readonly text: string;
+  /**
+   * Fills in the variables. `withPrompt` records the variables of the last call before it starts
+   * or inside it.
+   */
+  compile(variables?: PromptVariables): string;
+}
+
+export type Prompt = ChatPrompt | TextPrompt;
+
+interface GetPromptOptionsBase {
+  /** Fetch the version that this label points to. Default "production" when `version` is not set. */
+  label?: string;
+  /** Fetch this version number. Do not set it together with `label`. */
+  version?: number;
+  /** Seconds before a call fetches a kept prompt again, in the background. Default 60. */
+  cacheTtlSeconds?: number;
+  /** API key with the prompts:read scope. Falls back to the initialized client, then `TELEMETRY_DEV_API_KEY`. */
+  apiKey?: string;
+  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** Falls back to the initialized client's `fetch`, then `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+
+export interface GetChatPromptOptions extends GetPromptOptionsBase {
+  /** Default "chat". getPrompt rejects a prompt of the other type. */
+  type?: "chat";
+  /** Messages to use when the prompt cannot be fetched and no copy of it is kept. */
+  fallback?: readonly PromptMessage[];
+}
+
+export interface GetTextPromptOptions extends GetPromptOptionsBase {
+  type: "text";
+  /** Text to use when the prompt cannot be fetched and no copy of it is kept. */
+  fallback?: string;
+}
+
+export type GetPromptOptions = GetChatPromptOptions | GetTextPromptOptions;
+
+/**
+ * Why getPrompt failed. `code` is the code of the API error (`prompt_not_found`,
+ * `label_not_found`, `insufficient_scope`, `invalid_api_key`, …), or `missing_api_key`,
+ * `timeout`, `network_error`, `invalid_response`, or `type_mismatch`. A response with a different
+ * status and no API error gives `http_<status>`, for example `http_302` for a redirect: getPrompt
+ * does not go to the location of a redirect.
+ */
+export class PromptError extends Error {
+  override readonly name = "PromptError";
+
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status?: number,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+  }
+}
+
+interface PromptContent {
+  readonly messages: readonly PromptMessage[];
+  readonly text: string | null;
+  readonly model: PromptModel;
+  readonly parameters: PromptParameters;
+  readonly tools: readonly PromptTool[];
+  readonly responseFormat: PromptResponseFormat;
+}
+
+interface PromptResponse extends PromptContent {
+  readonly name: string;
+  readonly type: "chat" | "text";
+  readonly label: string | null;
+  readonly version: number;
+  readonly rollout: (PromptContent & { readonly percent: number; readonly version: number }) | null;
+}
+
+interface CacheEntry {
+  response?: PromptResponse;
+  /** Why the last fetch failed, when there was no response to keep. */
+  error?: unknown;
+  /** When the last fetch ended. */
+  checkedAt: number;
+  pending?: Promise<PromptResponse>;
+}
+
+/** The prompt of a `withPrompt` call and the variables that its spans record. */
+interface PromptScope {
+  readonly prompt: Prompt;
+  variables: object | undefined;
+}
+
+const FETCH_TIMEOUT_MS = 10_000;
+/** How long a failed fetch with no copy answers calls, so that they do not each fetch again. */
+const ERROR_TTL_MS = 10_000;
+const MAX_CACHE_ENTRIES = 1_000;
+const VARIABLE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const MODEL_CALL_OPERATIONS = new Set<unknown>(["chat", "text_completion", "generate_content"]);
+const PROMPT_KEY = createContextKey("telemetry.dev prompt");
+
+const cache = new Map<string, CacheEntry>();
+const compiledVariables = new WeakMap<Prompt, object>();
+
+/**
+ * Fetches a prompt version from telemetry.dev and keeps it. When the copy is older than
+ * `cacheTtlSeconds`, a call returns it at once and fetches a new one in the background. Only a call
+ * with no copy waits for a fetch, at most 10 seconds. Calls for the same prompt share one fetch.
+ * When a fetch fails, getPrompt returns the last copy that it kept; with no copy it returns
+ * `fallback`. With neither it rejects with a `PromptError`: unlike the telemetry functions,
+ * getPrompt cannot fail open, because the app cannot run without the prompt. With no copy, the
+ * calls of the next 10 seconds (or the TTL, if it is shorter) fail the same way without a fetch.
+ *
+ * A label with a gradual rollout gives each session one version: the choice uses the session id
+ * of `propagateAttributes`, or a random choice per call without one.
+ */
+export function getPrompt(name: string, options: GetTextPromptOptions): Promise<TextPrompt>;
+export function getPrompt(name: string, options?: GetChatPromptOptions): Promise<ChatPrompt>;
+export async function getPrompt(name: string, options: GetPromptOptions = {}): Promise<Prompt> {
+  const type = options.type ?? "chat";
+  checkOptions(name, options, type);
+
+  const core = currentClient().core;
+  const env = resolveEnv();
+  const apiKey = options.apiKey ?? core?.config.apiKey ?? env.TELEMETRY_DEV_API_KEY;
+
+  // An empty value counts as unset, as in the Python SDK.
+  const baseUrl = (
+    options.baseUrl ||
+    core?.config.baseUrl ||
+    env.TELEMETRY_DEV_BASE_URL ||
+    DEFAULT_BASE_URL
+  ).replace(/\/+$/, "");
+
+  const label = options.version === undefined ? (options.label ?? "production") : null;
+  const onError = core?.config.onError;
+  let response: PromptResponse;
+
+  try {
+    if (!apiKey) {
+      throw new PromptError(
+        "missing_api_key",
+        "No API key: pass apiKey or set TELEMETRY_DEV_API_KEY",
+      );
+    }
+
+    const url = new URL(`${baseUrl}/v1/prompts`);
+    url.searchParams.set("name", name);
+
+    if (label === null) url.searchParams.set("version", String(options.version));
+    else url.searchParams.set("label", label);
+
+    response = await load(
+      [
+        baseUrl,
+        keyFingerprint(apiKey),
+        name,
+        label === null ? `version:${options.version}` : `label:${label}`,
+      ].join("\0"),
+      (options.cacheTtlSeconds ?? 60) * 1000,
+      () =>
+        fetchPrompt(
+          url,
+          {
+            authorization: `Bearer ${apiKey}`,
+            "x-telemetry-dev-sdk": core?.config.sdkName ?? "@telemetry-dev/sdk",
+          },
+          options.fetch ?? core?.config.fetchImpl ?? globalThis.fetch,
+        ),
+      onError,
+    );
+  } catch (error) {
+    if (options.fallback === undefined) throw error;
+    reportError(onError, error);
+
+    return createPrompt({
+      name,
+      type,
+      label,
+      version: null,
+      isFallback: true,
+      content: {
+        messages: type === "chat" ? (options.fallback as readonly PromptMessage[]) : [],
+        text: type === "text" ? (options.fallback as string) : null,
+        model: null,
+        parameters: {},
+        tools: [],
+        responseFormat: { type: "text" },
+      },
+    });
+  }
+
+  if (response.type !== type) {
+    throw new PromptError(
+      "type_mismatch",
+      `${name} is a ${response.type} prompt; pass type: "${response.type}"`,
+    );
+  }
+
+  const chosen = response.rollout && inRollout(response) ? response.rollout : response;
+
+  return createPrompt({
+    name: response.name,
+    type,
+    label: response.label,
+    version: chosen.version,
+    isFallback: false,
+    content: chosen,
+  });
+}
+
+/**
+ * Runs `fn` with `prompt` as the prompt of each model call (generation span) that starts inside
+ * it: the spans get `td.prompt.name`, `td.prompt.version`, `td.prompt.label`, and, when input
+ * capture is on, `td.prompt.variables`. The variables are those of the last `compile()` of this
+ * prompt object before withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
+ * another task does not change them once withPrompt runs.
+ */
+export function withPrompt<T>(prompt: Prompt, fn: () => T): T {
+  const scope: PromptScope = { prompt, variables: compiledVariables.get(prompt) };
+
+  return withContext(activeContext().setValue(PROMPT_KEY, scope), fn);
+}
+
+/** The td.prompt.* attributes for a span with this operation that starts in `ctx`. */
+export function promptAttributes(
+  ctx: Context,
+  operation: unknown,
+  capture: FieldCaptureConfig,
+): Attributes | undefined {
+  if (!MODEL_CALL_OPERATIONS.has(operation)) return undefined;
+
+  const scope = (ctx.getValue(PROMPT_KEY) ?? activeContext().getValue(PROMPT_KEY)) as
+    | PromptScope
+    | undefined;
+
+  if (!scope) return undefined;
+  const { prompt, variables } = scope;
+
+  return omitUndefined({
+    "td.prompt.name": prompt.name,
+    "td.prompt.version": prompt.version ?? undefined,
+    "td.prompt.label": prompt.label ?? undefined,
+    "td.prompt.variables":
+      variables !== undefined && capture.captureInput
+        ? prepareCaptureValue("td.prompt.variables", variables, capture)
+        : undefined,
+  });
+}
+
+function checkOptions(name: string, options: GetPromptOptions, type: string): void {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("name must be a non-empty string");
+  }
+
+  if (type !== "chat" && type !== "text") throw new TypeError('type must be "chat" or "text"');
+
+  if (options.label !== undefined && options.version !== undefined) {
+    throw new TypeError("Pass label or version, not both");
+  }
+
+  if (
+    options.version !== undefined &&
+    (!Number.isSafeInteger(options.version) || options.version < 1)
+  ) {
+    throw new RangeError("version must be a positive integer");
+  }
+
+  const ttl = options.cacheTtlSeconds;
+
+  if (ttl !== undefined && !(Number.isFinite(ttl) && ttl >= 0)) {
+    throw new RangeError("cacheTtlSeconds must be a non-negative number");
+  }
+
+  if (
+    options.fallback !== undefined &&
+    (type === "chat" ? !Array.isArray(options.fallback) : typeof options.fallback !== "string")
+  ) {
+    throw new TypeError(
+      type === "chat" ? "fallback must be a list of messages" : "fallback must be a string",
+    );
+  }
+}
+
+/**
+ * Returns the kept copy of a prompt, and fetches a new copy in the background when it is older
+ * than the TTL. Only a call with no copy waits for a fetch. A failed fetch with no copy fails the
+ * calls of the next ERROR_TTL_MS (or the TTL, if it is shorter) without a fetch.
+ */
+async function load(
+  key: string,
+  ttlMs: number,
+  fetchResponse: () => Promise<PromptResponse>,
+  onError: ((cause: Error) => void) | undefined,
+): Promise<PromptResponse> {
+  let entry = cache.get(key);
+
+  if (!entry) {
+    if (cache.size >= MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value!);
+    entry = { checkedAt: 0 };
+    cache.set(key, entry);
+  }
+
+  const fresh =
+    Date.now() < entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS));
+
+  if (entry.response) {
+    if (!fresh) entry.pending ??= refresh(entry, fetchResponse, onError);
+
+    return entry.response;
+  }
+
+  if (fresh) throw entry.error;
+
+  return (entry.pending ??= refresh(entry, fetchResponse, onError));
+}
+
+function refresh(
+  entry: CacheEntry,
+  fetchResponse: () => Promise<PromptResponse>,
+  onError: ((cause: Error) => void) | undefined,
+): Promise<PromptResponse> {
+  return fetchResponse()
+    .then(
+      (response) => {
+        entry.response = response;
+
+        return response;
+      },
+      (error: unknown) => {
+        if (!entry.response) {
+          entry.error = error;
+          throw error;
+        }
+
+        reportError(onError, error);
+
+        return entry.response;
+      },
+    )
+    .finally(() => {
+      // A failed fetch counts too, so that calls do not each start a fetch while it fails.
+      entry.checkedAt = Date.now();
+      entry.pending = undefined;
+    });
+}
+
+async function fetchPrompt(
+  url: URL,
+  headers: Record<string, string>,
+  fetchImpl: typeof fetch,
+): Promise<PromptResponse> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const res = await fetchImpl(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+      // A redirect to another host must not get the API key, so a 3xx fails below like any status
+      // that is not OK. Cloudflare Workers reject redirect: "error".
+      redirect: "manual",
+    });
+
+    const body: unknown = await res.json().catch(() => undefined);
+
+    if (!res.ok) {
+      const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+
+      throw new PromptError(
+        typeof error.code === "string" ? error.code : `http_${res.status}`,
+        typeof error.message === "string" ? error.message : `telemetry.dev returned ${res.status}`,
+        res.status,
+      );
+    }
+
+    const response = parseResponse(body);
+
+    if (!response) {
+      throw new PromptError("invalid_response", "telemetry.dev returned a prompt it cannot read");
+    }
+
+    return response;
+  } catch (error) {
+    // The timeout can also cut the body, which then reads as an invalid response.
+    if (controller.signal.aborted) {
+      throw new PromptError("timeout", `Fetching the prompt took more than ${FETCH_TIMEOUT_MS} ms`);
+    }
+
+    if (error instanceof PromptError) throw error;
+
+    throw new PromptError("network_error", "Could not reach telemetry.dev", undefined, {
+      cause: error,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function createPrompt(input: {
+  name: string;
+  type: "chat" | "text";
+  label: string | null;
+  version: number | null;
+  isFallback: boolean;
+  content: Omit<PromptContent, "model"> & { readonly model: PromptModel | null };
+}): Prompt {
+  const { content, type } = input;
+
+  const prompt: Prompt = Object.freeze({
+    name: input.name,
+    type,
+    version: input.version,
+    label: input.label,
+    messages: content.messages,
+    text: content.text,
+    model: content.model,
+    parameters: content.parameters,
+    tools: content.tools,
+    responseFormat: content.responseFormat,
+    isFallback: input.isFallback,
+    compile(variables: PromptVariables<unknown> = {}) {
+      compiledVariables.set(prompt, variables);
+      const scope = activeContext().getValue(PROMPT_KEY) as PromptScope | undefined;
+
+      if (scope?.prompt === prompt) scope.variables = variables;
+
+      return type === "chat"
+        ? compileMessages(content.messages, variables)
+        : fill(content.text ?? "", variables);
+    },
+  }) as Prompt;
+
+  return prompt;
+}
+
+function compileMessages(
+  messages: readonly PromptMessage[],
+  variables: PromptVariables<unknown>,
+): unknown[] {
+  return messages.flatMap((message) => {
+    if (message.role !== "placeholder") {
+      return [{ role: message.role, content: fill(message.content, variables) }];
+    }
+
+    const value = Object.hasOwn(variables, message.name) ? variables[message.name] : undefined;
+
+    if (value == null) return [];
+
+    if (!Array.isArray(value)) {
+      throw new TypeError(`The ${message.name} variable must be a list of messages`);
+    }
+
+    return value;
+  });
+}
+
+function fill(text: string, variables: PromptVariables<unknown>): string {
+  return text.replace(VARIABLE, (_tag, name: string) => {
+    const value = Object.hasOwn(variables, name) ? variables[name] : undefined;
+
+    if (value == null) return "";
+
+    return typeof value === "string" ? value : (jsonAttr(value) ?? "");
+  });
+}
+
+// One session keeps one version: FNV-1a 32-bit of "<name>:<label>:<session id>", mod 100.
+function inRollout(response: PromptResponse): boolean {
+  const sessionId = sessionIdOf(activeContext()) ?? currentClient().core?.config.processSessionId;
+
+  const bucket =
+    sessionId === undefined
+      ? Math.floor(Math.random() * 100)
+      : fnv1a(`${response.name}:${response.label}:${sessionId}`) % 100;
+
+  return bucket < response.rollout!.percent;
+}
+
+function fnv1a(text: string): number {
+  let hash = 2166136261;
+
+  for (const byte of new TextEncoder().encode(text)) {
+    hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+  }
+
+  return hash;
+}
+
+function keyFingerprint(apiKey: string): string {
+  const digest = sha256(new TextEncoder().encode(apiKey)).subarray(0, 16);
+
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function parseResponse(body: unknown): PromptResponse | undefined {
+  if (!isRecord(body)) return undefined;
+  const { name, type, label, version, rollout } = body;
+
+  if (
+    typeof name !== "string" ||
+    (type !== "chat" && type !== "text") ||
+    (label !== null && typeof label !== "string") ||
+    !isVersion(version)
+  ) {
+    return undefined;
+  }
+
+  const content = parseContent(body, type);
+
+  if (!content) return undefined;
+
+  if (rollout == null) return deepFreeze({ name, type, label, version, ...content, rollout: null });
+
+  if (
+    !isRecord(rollout) ||
+    !isVersion(rollout.version) ||
+    !Number.isInteger(rollout.percent) ||
+    (rollout.percent as number) < 0 ||
+    (rollout.percent as number) > 100
+  ) {
+    return undefined;
+  }
+
+  const rolloutContent = parseContent(rollout, type);
+
+  if (!rolloutContent) return undefined;
+
+  return deepFreeze({
+    name,
+    type,
+    label,
+    version,
+    ...content,
+    rollout: { percent: rollout.percent as number, version: rollout.version, ...rolloutContent },
+  });
+}
+
+function parseContent(
+  value: Record<string, unknown>,
+  type: "chat" | "text",
+): PromptContent | undefined {
+  const { messages, text, model, parameters, tools, responseFormat } = value;
+
+  const validBody =
+    type === "chat"
+      ? Array.isArray(messages) && messages.every(isPromptMessage)
+      : typeof text === "string";
+
+  if (
+    !validBody ||
+    !isRecord(model) ||
+    typeof model.provider !== "string" ||
+    typeof model.name !== "string" ||
+    !isRecord(parameters) ||
+    !Array.isArray(tools) ||
+    !tools.every((tool) => isRecord(tool) && typeof tool.name === "string") ||
+    !isRecord(responseFormat) ||
+    typeof responseFormat.type !== "string"
+  ) {
+    return undefined;
+  }
+
+  return {
+    messages: type === "chat" ? (messages as PromptMessage[]) : [],
+    text: type === "text" ? (text as string) : null,
+    model: model as unknown as PromptModel,
+    parameters: parameters as PromptParameters,
+    tools: tools as PromptTool[],
+    responseFormat: responseFormat as unknown as PromptResponseFormat,
+  };
+}
+
+function isPromptMessage(value: unknown): value is PromptMessage {
+  if (!isRecord(value)) return false;
+
+  return value.role === "placeholder"
+    ? typeof value.name === "string"
+    : (value.role === "system" || value.role === "user" || value.role === "assistant") &&
+        typeof value.content === "string";
+}
+
+function isVersion(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 1;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Prompt objects share the cached response, so an app cannot change the cache through them.
+function deepFreeze<T>(value: T): T {
+  if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+
+    for (const item of Object.values(value)) deepFreeze(item);
+  }
+
+  return value;
+}

package/src/span.ts

@@ -41,6 +41,7 @@ import {
 import { prepareCaptureValue } from "./capture.ts";
 import { type ClientCore, currentClient } from "./client.ts";
 import { NOOP_SPAN_HANDLE } from "./noop.ts";
+import { promptAttributes } from "./prompts.ts";
 
 export type ParentRef = string /* W3C traceparent */ | SpanHandle | SpanContext | Context;
 
@@ -229,6 +230,7 @@ export function createSpanHandle(
 
   const parentCtx = withSessionParent(sessionContext, sessionId, core.config.apiKey);
   const attrs = fieldsToAttributes(options, meta.type, meta.capture);
+  const operation = attrs["gen_ai.operation.name"] ?? SPAN_TYPE_OPERATIONS[meta.type];
 
   const span = core.tracer.startSpan(
     name,
@@ -239,6 +241,7 @@ export function createSpanHandle(
       attributes: {
         "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type],
         ...propagatedFromContext(parentCtx),
+        ...promptAttributes(parentCtx, operation, meta.capture),
         ...attrs,
       },
     },