@to11ai/sdk 1.1.0 → 2.0.0-rc.2

package/src/context.ts

@@ -0,0 +1,198 @@
+/**
+ * Observability context — the `session → conversation → turn` hierarchy that
+ * maps onto to11's telemetry grouping (Session → Conversation → Turn →
+ * LLM-Call). Each level provides a lazy default for the level below; explicit
+ * control is opt-in per use case. See
+ * docs/product-specs/2026-07-14-to11-2691-sdk-simpler-setup.md.
+ *
+ * Header-only: `turn.headers(prompt?)` returns a plain object the caller applies
+ * to their own provider client. It never sends a request.
+ */
+
+import {
+	type GatewayPromptProvenance,
+	gatewayAuthHeaders,
+	gatewayPromptHeaders,
+} from "./gateway";
+
+/** Auth/config the client hands to the context for gateway header building. */
+export interface TurnAuthContext {
+	readonly apiKey: string;
+	readonly projectId: string;
+	readonly env?: string;
+}
+
+/**
+ * A prompt argument accepted by `turn.headers()`. Either the flat provenance
+ * (a neutral `RenderedPrompt`) or a `format`-shaped result carrying it under
+ * `metadata` — both are accepted so the format and neutral render paths carry
+ * provenance identically.
+ */
+export type PromptForHeaders =
+	| GatewayPromptProvenance
+	| { metadata: GatewayPromptProvenance };
+
+function randomHex(bytes: number): string {
+	const buf = new Uint8Array(bytes);
+	crypto.getRandomValues(buf);
+	let out = "";
+	for (const b of buf) out += b.toString(16).padStart(2, "0");
+	return out;
+}
+
+/** A fresh, sampled W3C `traceparent` (`00-<32hex>-<16hex>-01`). */
+function newTraceparent(): string {
+	return `00-${randomHex(16)}-${randomHex(8)}-01`;
+}
+
+function newId(): string {
+	return crypto.randomUUID();
+}
+
+function provenanceOf(prompt: PromptForHeaders): GatewayPromptProvenance {
+	return "metadata" in prompt ? prompt.metadata : prompt;
+}
+
+/**
+ * One agent turn — a single trace. A turn's `traceparent` is fixed for its
+ * lifetime, so every LLM-call made under it groups into one trace.
+ */
+export class Turn {
+	/** The fixed W3C traceparent for this turn (one trace). */
+	readonly traceparent: string;
+
+	constructor(
+		private readonly auth: TurnAuthContext,
+		readonly sessionId: string,
+		readonly conversationId: string,
+		traceparent?: string,
+	) {
+		this.traceparent = traceparent ?? newTraceparent();
+	}
+
+	/**
+	 * The complete gateway header bag: auth + session + conversation +
+	 * traceparent, plus prompt provenance when a `prompt` is supplied. A pure
+	 * read of the turn's fixed ids — reuse it across a tool-loop or call per
+	 * request; the result is identical.
+	 *
+	 * Only valid for requests targeting the gateway (`GATEWAY_URL`); it carries
+	 * the to11 API key and must never be attached to a direct provider endpoint.
+	 *
+	 * @example One call (inline turn)
+	 * const res = await openai.chat.completions.create(
+	 *   { ...prompt.config, messages: prompt.messages },
+	 *   { headers: to11.turn().headers(prompt) },
+	 * );
+	 *
+	 * @example Tool loop — hoist the turn so every call shares one trace
+	 * const turn = to11.turn();
+	 * const headers = turn.headers(prompt);
+	 * while (true) {
+	 *   const res = await openai.chat.completions.create({ ...prompt.config, messages, tools }, { headers });
+	 *   // …reuse `headers` for every call in the loop…
+	 * }
+	 */
+	headers(prompt?: PromptForHeaders): Record<string, string> {
+		const headers: Record<string, string> = {
+			...gatewayAuthHeaders({
+				apiKey: this.auth.apiKey,
+				projectId: this.auth.projectId,
+				...(this.auth.env !== undefined ? { env: this.auth.env } : {}),
+			}),
+			"x-to11-session-id": this.sessionId,
+			"x-to11-conversation-id": this.conversationId,
+			traceparent: this.traceparent,
+		};
+		if (prompt !== undefined) {
+			Object.assign(headers, gatewayPromptHeaders(provenanceOf(prompt)));
+		}
+		return headers;
+	}
+}
+
+/** One agent thread — a stable conversation id shared across all its turns. */
+export class Conversation {
+	/** Stable conversation id, reused by every turn created from this object. */
+	readonly id: string;
+
+	constructor(
+		private readonly auth: TurnAuthContext,
+		readonly sessionId: string,
+		id?: string,
+	) {
+		this.id = id ?? newId();
+	}
+
+	/** Start a new turn (fresh trace) in this conversation. */
+	turn(): Turn {
+		return new Turn(this.auth, this.sessionId, this.id);
+	}
+}
+
+/**
+ * One unit of work. Groups conversations under a single session id. A session
+ * lazily owns one default conversation, used by `session.turn()`; call
+ * `session.conversation()` for additional (side/parallel) agent threads.
+ */
+export class Session {
+	/** Stable session id, carried by every conversation and turn beneath it. */
+	readonly id: string;
+	private defaultConversation: Conversation | undefined;
+
+	constructor(
+		private readonly auth: TurnAuthContext,
+		id?: string,
+	) {
+		this.id = id ?? newId();
+	}
+
+	/**
+	 * Create a distinct conversation (a separate agent thread) in this session.
+	 * Use this when one unit of work runs multiple agents (side / parallel
+	 * agents): each conversation gets its own `x-to11-conversation-id`, all under
+	 * the one session.
+	 *
+	 * @example Multiple agents in one session
+	 * const session  = to11.session();
+	 * const main     = session.conversation();   // main agent thread
+	 * const research = session.conversation();   // separate research thread, same session
+	 *
+	 * await openai.chat.completions.create(
+	 *   { ...mainPrompt.config, messages: mainMessages },
+	 *   { headers: main.turn().headers(mainPrompt) },
+	 * );
+	 * await openai.chat.completions.create(
+	 *   { ...researchPrompt.config, messages: researchMessages },
+	 *   { headers: research.turn().headers(researchPrompt) },
+	 * );
+	 */
+	conversation(id?: string): Conversation {
+		return new Conversation(this.auth, this.id, id);
+	}
+
+	/**
+	 * Start a turn in the session's single implicit conversation. The default
+	 * conversation is created lazily on first call and reused, so consecutive
+	 * `session.turn()` calls share one `x-to11-conversation-id` (each with its
+	 * own `traceparent`).
+	 *
+	 * @example Multi-turn chat — every turn shares the session's conversation
+	 * const session = to11.session();
+	 * for await (const input of inputs) {
+	 *   messages.push({ role: "user", content: input });
+	 *   const turn = session.turn(); // fresh trace, same conversation id
+	 *   const res = await openai.chat.completions.create(
+	 *     { ...prompt.config, messages },
+	 *     { headers: turn.headers(prompt) },
+	 *   );
+	 *   messages.push(res.choices[0].message);
+	 * }
+	 */
+	turn(): Turn {
+		if (this.defaultConversation === undefined) {
+			this.defaultConversation = this.conversation();
+		}
+		return this.defaultConversation.turn();
+	}
+}

package/src/errors.ts

@@ -113,6 +113,36 @@ export class To11aiResponseValidationError extends To11aiError {
 	}
 }
 
+/**
+ * Thrown by the provider-shape converters (`toOpenAIMessages` /
+ * `toAnthropicMessages`, and `render({ format })`) in `onUnknownRole: "error"`
+ * mode when a message carries a role outside the known set
+ * (`system | user | assistant | developer | tool`). `code` is the stable
+ * `"unknown_role"` slug; `role` / `index` locate the offending turn.
+ *
+ * A client-side conversion error — it extends `To11aiError` (not
+ * `To11aiApiError`), so it never carries an HTTP status.
+ */
+export class UnknownRoleError extends To11aiError {
+	readonly code = "unknown_role";
+	readonly role: string;
+	readonly index: number;
+
+	constructor(role: string, index: number) {
+		super(
+			`[to11ai/sdk] message[${index}] has unknown role ${JSON.stringify(role)}; expected system|user|assistant|developer|tool`,
+		);
+		this.name = "UnknownRoleError";
+		this.role = role;
+		this.index = index;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is UnknownRoleError {
+		return err instanceof UnknownRoleError;
+	}
+}
+
 /**
  * Thrown when strict-mode rejects a label move for an unregistered label.
  *
@@ -252,7 +282,7 @@ export class EnvNotEnabledForProviderError extends To11aiApiError {
 
 // ─── Prompt resolution typed errors (TO11-980 / S9) ────────────────────────
 //
-// These four subclasses give `prompts.fetch()` callers a discriminable error
+// These four subclasses give `prompts.render()` callers a discriminable error
 // family for prompt resolution. Each:
 //   - extends `To11aiApiError`, so existing broad `catch (err instanceof
 //     To11aiApiError)` blocks keep matching (AC8),
@@ -327,7 +357,7 @@ export interface EnvNotFoundReason {
 }
 
 /**
- * Thrown when no serving environment can be resolved for a `prompts.fetch()`
+ * Thrown when no serving environment can be resolved for a `prompts.render()`
  * call. One class, two `reason.source` discriminants (see
  * `EnvNotFoundReason`): client-eager `"missing"` (R4) and server-forwarded
  * `"unknown"` (`ENV_NOT_FOUND`).
@@ -357,7 +387,7 @@ export class EnvNotFoundError extends To11aiApiError {
 	/** Build the client-eager (missing-at-both) variant — no transport call. */
 	static missing(env?: string): EnvNotFoundError {
 		return new EnvNotFoundError(
-			"[to11ai/sdk] No environment resolvable for prompts.fetch(): none supplied at client init and none supplied per call. Pass `env` to createClient or fetch(slug, { env }).",
+			"[to11ai/sdk] No environment resolvable for prompts.render(): none supplied at client init and none supplied per call. Pass `env` to createClient or render(slug, { env }).",
 			{ env, source: "missing" },
 			undefined,
 			0,

package/src/gateway.ts

@@ -1,9 +1,10 @@
+import { UnknownRoleError } from "./errors";
 import {
 	ENV_SLUG_REGEX,
-	type FetchedPrompt,
 	type RenderedChatMessage,
 	type ResolvedPrompt,
 	type ResolvedToolDefinition,
+	type UnknownRoleMode,
 } from "./prompts/types";
 
 export interface GatewayAuthOptions {
@@ -57,7 +58,7 @@ export function gatewayAuthHeaders(
 		}
 		// Enforce the project-environments registry slug rule (lowercase-kebab,
 		// 1-63 chars) eagerly — same `ENV_SLUG_REGEX` already applied on the
-		// createClient / fetch() paths — so a misconfigured env (e.g. "Prod",
+		// createClient / render() paths — so a misconfigured env (e.g. "Prod",
 		// "bad env", >63 chars) fails locally with a clear SDK error instead of
 		// being copied verbatim into x-to11-env and rejected later at the
 		// gateway/API boundary (TO11-1424).
@@ -78,44 +79,66 @@ export function gatewayAuthHeaders(
  * follows from a resolved prompt:
  *   - `x-to11-prompt-id`, `x-to11-prompt-version` — always.
  *   - `x-to11-release-id` — when the result carries a non-null `releaseId`
- *     (the enriched `fetch()` result; a legacy `resolve()` result has no
+ *     (the enriched `render()` result; a legacy `resolve()` result has no
  *     `releaseId`, so it is omitted — non-breaking).
  *   - `x-to11-variant-name` — IFF `variantName` is present (i.e. the resolved
  *     release was weighted); omitted for `single`-strategy releases.
- *   - `x-to11-prompt-labels` — omitted when empty (the gateway rejects empty
- *     header values); behavior unchanged.
+ *   - `x-to11-prompt-label` — the single label the prompt resolved through (the
+ *     env slug today); omitted when empty (the gateway rejects empty values).
+ *   - `x-to11-prompt-slug` — the prompt's human-readable slug, so traces show a
+ *     readable name alongside the opaque `x-to11-prompt-id`; omitted when empty
+ *     or absent (a legacy `resolve()` result carries no slug).
  *
- * The parameter type is WIDENED to accept either the enriched `fetch()`
+ * The parameter type is WIDENED to accept either the enriched `render()`
  * result or the legacy `ResolvedPrompt`. The new fields are read when present
  * and omitted otherwise, so an old `resolve()` result still produces exactly
  * the original three headers (non-breaking; D1/D7 shape coexistence).
  *
  * @example
- * const result = await client.prompts.fetch(slug, { env: "prod" });
+ * const result = await client.prompts.render(slug, { env: "prod" });
  * const headers = gatewayPromptHeaders(result);
  */
+export interface GatewayPromptProvenance {
+	promptId: string;
+	version: number;
+	/** The single label the prompt resolved through (env slug today). */
+	label: string;
+	/**
+	 * The prompt's human-readable slug (the `render()`/`resolve()` input). Present
+	 * on an enriched `render()` result; a legacy `ResolvedPrompt` omits it.
+	 */
+	slug?: string;
+	/** Present on an enriched result; a legacy `resolve()` result omits it. */
+	releaseId?: string | null;
+	/** Present IFF the resolved release was weighted. */
+	variantName?: string;
+}
+
 export function gatewayPromptHeaders(
-	prompt: ResolvedPrompt | FetchedPrompt,
+	prompt: GatewayPromptProvenance,
 ): Record<string, string> {
 	const headers: Record<string, string> = {
 		"x-to11-prompt-id": prompt.promptId,
 		"x-to11-prompt-version": String(prompt.version),
 	};
-	// `releaseId` is present only on the enriched fetch() result; emit the
-	// header only for a non-null release id (the offline-fallback path can
-	// carry an explicit `null`, which is omitted — the gateway rejects empty
-	// header values).
-	const releaseId = (prompt as Partial<FetchedPrompt>).releaseId;
-	if (typeof releaseId === "string" && releaseId.length > 0) {
-		headers["x-to11-release-id"] = releaseId;
+	// Emit the release id only when it is a non-null, non-empty string — the
+	// offline-fallback path can carry an explicit `null`, and the gateway
+	// rejects empty header values.
+	if (typeof prompt.releaseId === "string" && prompt.releaseId.length > 0) {
+		headers["x-to11-release-id"] = prompt.releaseId;
+	}
+	if (typeof prompt.variantName === "string" && prompt.variantName.length > 0) {
+		headers["x-to11-variant-name"] = prompt.variantName;
 	}
-	// `variantName` is present IFF the release was weighted (R7).
-	const variantName = (prompt as Partial<FetchedPrompt>).variantName;
-	if (typeof variantName === "string" && variantName.length > 0) {
-		headers["x-to11-variant-name"] = variantName;
+	// The single label the prompt resolved through. Omit when empty — the
+	// gateway rejects empty header values.
+	if (prompt.label.length > 0) {
+		headers["x-to11-prompt-label"] = prompt.label;
 	}
-	if (prompt.labels.length > 0) {
-		headers["x-to11-prompt-labels"] = prompt.labels.join(",");
+	// The prompt's human-readable slug. Omit when absent/empty — a legacy
+	// `resolve()` result carries no slug, and the gateway rejects empty values.
+	if (typeof prompt.slug === "string" && prompt.slug.length > 0) {
+		headers["x-to11-prompt-slug"] = prompt.slug;
 	}
 	return headers;
 }
@@ -307,6 +330,47 @@ function requireToolCallId(id: string | undefined | null): string {
 	return id;
 }
 
+/** Options shared by the message converters. */
+export interface ConvertMessagesOptions {
+	/**
+	 * Policy for a message whose role is outside the known set
+	 * (`system | user | assistant | developer | tool`). `"drop"` (default) omits
+	 * it silently; `"warn"` omits it and emits a `console.warn`; `"error"` throws
+	 * {@link UnknownRoleError}. Both converters apply this identically.
+	 */
+	onUnknownRole?: UnknownRoleMode;
+}
+
+const KNOWN_RENDERED_ROLES: ReadonlySet<string> = new Set([
+	"system",
+	"user",
+	"assistant",
+	"developer",
+	"tool",
+]);
+
+/**
+ * Apply the unknown-role policy to a message. Returns `true` when the caller
+ * should skip (drop) the message; throws in `"error"` mode. A known role
+ * returns `false` (keep). Both converters route through this so their handling
+ * of unrecognized roles is identical — no silent divergence.
+ */
+function skipUnknownRole(
+	role: string,
+	index: number,
+	mode: UnknownRoleMode,
+): boolean {
+	if (KNOWN_RENDERED_ROLES.has(role)) return false;
+	if (mode === "error") throw new UnknownRoleError(role, index);
+	if (mode === "warn") {
+		console.warn(
+			`[to11ai/sdk] dropped message[${index}] with unknown role ${JSON.stringify(role)} (expected system|user|assistant|developer|tool)`,
+		);
+	}
+	// "drop": silent.
+	return true;
+}
+
 /**
  * Shape rendered turns for the OpenAI Chat Completions `messages` field.
  *
@@ -316,28 +380,37 @@ function requireToolCallId(id: string | undefined | null): string {
  *   become `tool_calls[]` with JSON-stringified `arguments` (the OpenAI wire
  *   shape). A pure tool-call turn keeps `content: null`.
  * - `tool` (result) → `{ role: "tool", tool_call_id, content }`.
+ * - an unrecognized role is handled per `options.onUnknownRole` (default
+ *   `"drop"`) — dropped, dropped-with-warning, or throws `UnknownRoleError`.
  *
  * @example
  * const messages = toOpenAIMessages(prompt.messages);
+ * @example Fail loudly on a malformed message array
+ * const messages = toOpenAIMessages(history, { onUnknownRole: "error" });
  */
 export function toOpenAIMessages(
 	messages: ReadonlyArray<RenderedChatMessage>,
+	options: ConvertMessagesOptions = {},
 ): OpenAIChatMessage[] {
-	return messages.map((message) => {
+	const mode = options.onUnknownRole ?? "drop";
+	const out: OpenAIChatMessage[] = [];
+	messages.forEach((message, index) => {
+		if (skipUnknownRole(message.role, index, mode)) return;
 		if (message.role === "tool") {
-			return {
+			out.push({
 				role: "tool",
 				tool_call_id: requireToolCallId(message.toolCallId),
 				content: message.content ?? "",
-			};
+			});
+			return;
 		}
 		if (message.role === "assistant") {
-			const out: OpenAIChatMessage = {
+			const msg: OpenAIChatMessage = {
 				role: "assistant",
 				content: message.content ?? null,
 			};
 			if (message.toolCalls != null && message.toolCalls.length > 0) {
-				out.tool_calls = message.toolCalls.map((call) => ({
+				msg.tool_calls = message.toolCalls.map((call) => ({
 					id: requireToolCallId(call.id),
 					type: "function",
 					function: {
@@ -346,10 +419,12 @@ export function toOpenAIMessages(
 					},
 				}));
 			}
-			return out;
+			out.push(msg);
+			return;
 		}
-		return { role: message.role, content: message.content ?? "" };
+		out.push({ role: message.role, content: message.content ?? "" });
 	});
+	return out;
 }
 
 /**
@@ -364,18 +439,28 @@ export function toOpenAIMessages(
  *   ...tool_use] }`; without calls → `{ role: "assistant", content }`.
  * - `tool` (result) → `{ role: "user", content: [{ type: "tool_result",
  *   tool_use_id, content }] }`.
+ * - an unrecognized role is handled per `options.onUnknownRole` (default
+ *   `"drop"`) — dropped, dropped-with-warning, or throws `UnknownRoleError` —
+ *   identically to {@link toOpenAIMessages}. (`system`/`developer` are known
+ *   roles folded into `system`, not "unknown"; they are never dropped here.)
  *
  * @example
  * const messages = toAnthropicMessages(prompt.messages);
+ * @example Fail loudly on a malformed message array
+ * const messages = toAnthropicMessages(history, { onUnknownRole: "error" });
  */
 export function toAnthropicMessages(
 	messages: ReadonlyArray<RenderedChatMessage>,
+	options: ConvertMessagesOptions = {},
 ): AnthropicMessage[] {
+	const mode = options.onUnknownRole ?? "drop";
 	const out: AnthropicMessage[] = [];
-	for (const message of messages) {
+	messages.forEach((message, index) => {
 		if (message.role === "system" || message.role === "developer") {
-			continue;
+			// Folded into the top-level `system` via toAnthropicSystem — not dropped.
+			return;
 		}
+		if (skipUnknownRole(message.role, index, mode)) return;
 		if (message.role === "tool") {
 			out.push({
 				role: "user",
@@ -387,7 +472,7 @@ export function toAnthropicMessages(
 					},
 				],
 			});
-			continue;
+			return;
 		}
 		if (message.role === "assistant") {
 			if (message.toolCalls != null && message.toolCalls.length > 0) {
@@ -407,10 +492,40 @@ export function toAnthropicMessages(
 			} else {
 				out.push({ role: "assistant", content: message.content ?? "" });
 			}
-			continue;
+			return;
 		}
 		// `user`
 		out.push({ role: "user", content: message.content ?? "" });
-	}
+	});
 	return out;
 }
+
+/**
+ * Fold the `system` and `developer` instruction turns into Anthropic's
+ * top-level `system` string. Anthropic has no `developer` role and takes system
+ * instructions as a separate request field, so pair this with
+ * {@link toAnthropicMessages} (which omits those turns). Returns `undefined`
+ * when there is no system/developer content.
+ *
+ * @example
+ * const res = await anthropic.messages.create(
+ *   {
+ *     ...prompt.config,
+ *     system: toAnthropicSystem(prompt.messages),
+ *     messages: toAnthropicMessages(prompt.messages),
+ *   },
+ *   { headers: to11.turn().headers(prompt) },
+ * );
+ */
+export function toAnthropicSystem(
+	messages: ReadonlyArray<RenderedChatMessage>,
+): string | undefined {
+	const parts: string[] = [];
+	for (const message of messages) {
+		if (message.role !== "system" && message.role !== "developer") continue;
+		if (typeof message.content === "string" && message.content.length > 0) {
+			parts.push(message.content);
+		}
+	}
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}