@to11ai/sdk 2.0.0-rc.3 → 2.0.0-rc.5

package/src/client.ts

@@ -8,46 +8,30 @@ import {
 } from "./context";
 import { gatewayAuthHeaders } from "./gateway";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
-import type { CacheConfig } from "./prompts/cache";
 import { PromptResource } from "./prompts/resource";
 import {
 	ENV_SLUG_REGEX,
 	type RenderFormat,
 	type UnknownRoleMode,
 } from "./prompts/types";
-import { RoutingRulesResource } from "./routingRules/resource";
 import { Transport } from "./transport";
 
-// SDK-behavior delivery (TO11-2100): the resolution store + helpers.
-export {
-	BehaviorStore,
-	type BehaviorStoreOptions,
-	envVarNameForKey,
-	type SdkBehaviorEnvelope,
-} from "./behaviors/store";
 export type { TurnAuthContext } from "./context";
 export { Conversation, Session, Turn } from "./context";
 // Re-export all error types for convenience
 export type {
-	AmbiguousEnvLabelsReason,
-	EnvNotFoundReason,
 	NoActiveReleaseReason,
-	NoApplicableRouteReason,
 	PromptNotFoundReason,
 	PromptPolicyViolationReason,
 } from "./errors";
 export {
 	// TO11-980 (S9) prompt-resolution typed errors.
-	AmbiguousEnvLabelsError,
-	EnvNotEnabledForProviderError,
-	EnvNotFoundError,
+	LabelNotFoundError,
+	MissingLabelError,
 	NoActiveReleaseError,
-	NoApplicableRouteError,
 	PromptLabelNotRegisteredError,
 	PromptNotFoundError,
 	PromptPolicyViolationError,
-	RuleNotFoundError,
-	RuleVersionInvalidSnapshotError,
 	To11aiApiError,
 	To11aiAuthError,
 	To11aiError,
@@ -75,7 +59,6 @@ export type {
 	UpdateProjectEnvironmentResult,
 } from "./projectEnvironments/resource";
 export { ProjectEnvironmentResource } from "./projectEnvironments/resource";
-export type { CacheConfig } from "./prompts/cache";
 export type { PromptResourceConfig } from "./prompts/resource";
 export { PromptResource } from "./prompts/resource";
 export type {
@@ -92,42 +75,9 @@ export type {
 	RenderedPrompt,
 	RenderFormat,
 	RenderOptions,
-	ResolvedPrompt,
-	ResolvedPromptEnvelope,
 	UnknownRoleMode,
 } from "./prompts/types";
 export { ENV_SLUG_REGEX } from "./prompts/types";
-export type {
-	CreateRuleVersionInput,
-	CreateRuleVersionResult,
-	GetRuleVersionInput,
-	GetRuleVersionResult,
-	ListRuleReleasesInput,
-	ListRuleReleasesResult,
-	ListRuleVersionsInput,
-	ListRuleVersionsResult,
-	RollbackRuleReleaseInput,
-	RollbackRuleReleaseResult,
-	RuleModelBinding,
-	RuleProviderRef,
-	RuleRelease,
-	RuleReleaseActorType,
-	RuleReleaseApprovalStatus,
-	RuleReleaseChangeKind,
-	RuleReleaseStrategy,
-	RuleReleaseWeight,
-	RuleSnapshot,
-	RuleStrategy,
-	RuleVersion,
-	SetRuleReleaseInput,
-	SetRuleReleaseResult,
-} from "./routingRules/resource";
-export {
-	RoutingRuleReleaseResource,
-	RoutingRulesResource,
-	RoutingRuleVersionResource,
-} from "./routingRules/resource";
-export type { Transport } from "./transport";
 
 // ─── Client options ────────────────────────────────────────────────────────
 
@@ -143,12 +93,11 @@ export interface ClientOptions {
 	 */
 	gatewayUrl?: string;
 	/**
-	 * API key for server-side use. Precedence: this option → `TO11_API_KEY` env.
-	 * Rejected in browser contexts — use `getAccessToken` there.
+	 * API key for server-side use (server, CLI, backend job). Precedence: this
+	 * option → `TO11_API_KEY` env. Required. Rejected in browser contexts — a
+	 * to11 API key carries gateway access and must never ship in client code.
 	 */
 	apiKey?: string;
-	/** Token callback for browser / edge contexts — avoids static secrets. */
-	getAccessToken?: () => Promise<string>;
 	/**
 	 * Provider API key (BYOK) carried by `openaiOptions()` / `anthropicOptions()`
 	 * as the provider client's `apiKey`, so a BYOK call is a single
@@ -183,17 +132,10 @@ export interface ClientOptions {
 	 * via `render(slug, { onUnknownRole })`.
 	 */
 	onUnknownRole?: UnknownRoleMode;
-	/** LRU cache configuration for render(). Defaults: ttlSeconds=300, maxEntries=100 */
-	cache?: CacheConfig;
 	/** Request timeout in milliseconds. Default: 30_000 */
 	timeoutMs?: number;
 	/** Max retry attempts for network errors / 5xx. Default: 3 */
 	maxRetries?: number;
-	/**
-	 * Purely local overrides for server-evaluated SDK-behavior flags (TO11-2100).
-	 * An init option here wins over a `TO11_SDK_BEHAVIOR_*` env var. No LaunchDarkly.
-	 */
-	behaviorOverrides?: Record<string, unknown>;
 }
 
 // ─── Provider-client options (openaiOptions / anthropicOptions) ─────────────
@@ -230,19 +172,10 @@ export type ProviderClientOptions<
 export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
 	readonly prompts: PromptResource<F>;
 	readonly projectEnvironments: ProjectEnvironmentResource;
-	readonly routingRules: RoutingRulesResource;
-	/**
-	 * Resolve a server-evaluated SDK-behavior flag value (TO11-2100) under the
-	 * fixed precedence: local override (init option → `TO11_SDK_BEHAVIOR_*` env
-	 * var) → server-delivered value (captured from responses the client has
-	 * already made) → the `codedDefault` passed here. A value whose runtime type
-	 * disagrees with `codedDefault` falls through to the next tier. The SDK
-	 * carries no LaunchDarkly dependency; this only reads what the server
-	 * delivered on the envelope.
-	 */
-	readonly resolveBehavior: <T>(key: string, codedDefault: T) => T;
-	/** Resolved API key (server mode); `undefined` in browser (`getAccessToken`) mode. */
-	readonly apiKey: string | undefined;
+	/** Resolved API key (option → `TO11_API_KEY`). */
+	readonly apiKey: string;
+	/** Resolved control-plane base URL (option → `TO11_API_URL` → default). */
+	readonly baseUrl: string;
 	/** Resolved data-plane gateway URL (option → `TO11_GATEWAY_URL` → default). */
 	readonly gatewayUrl: string;
 	/**
@@ -251,6 +184,11 @@ export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
 	 * already default to it, so you don't need to pass it back into calls.
 	 */
 	readonly projectId: string | undefined;
+	/**
+	 * Resolved default serving environment (option → `TO11_ENV`); `undefined`
+	 * when none is configured. `prompts.render()` already defaults to it.
+	 */
+	readonly env: string | undefined;
 	/** A new session (unit of work). Pass an id to group telemetry by your own id. */
 	session(id?: string): Session;
 	/**
@@ -299,9 +237,8 @@ export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
  *  - URLs (`baseUrl` / `gatewayUrl`) — option → env var → built-in default.
  *  - `apiKey` / `projectId` — option → env var (no default).
  *  - `env` / `format` — option only.
- * Auth mode:
- *  - `apiKey` (or `TO11_API_KEY`) → server-side; rejected in browser contexts.
- *  - `getAccessToken`             → browser-safe; token fetched per request.
+ * Authenticate with `apiKey` (or `TO11_API_KEY`) — required, and server-side
+ * only (server, CLI, backend job); constructing with `apiKey` in a browser throws.
  *
  * @example Minimal setup (single call)
  * import { createClient } from "@to11ai/sdk";
@@ -371,15 +308,7 @@ export function createClient<
 	)
 		.replace(/\/+$/, "")
 		.replace(/\/v1$/, "");
-	const getAccessToken = options.getAccessToken;
-	// Explicit token auth suppresses an ambient `TO11_API_KEY` so a shared env
-	// (SSR / CI / edge) can't defeat an explicit `getAccessToken`. Only an
-	// *explicit* `options.apiKey` alongside `getAccessToken` stays ambiguous and
-	// is rejected by the exactly-one check below.
-	const apiKey =
-		getAccessToken !== undefined
-			? options.apiKey
-			: pick(options.apiKey, "TO11_API_KEY");
+	const apiKey = pick(options.apiKey, "TO11_API_KEY");
 	const projectId = pick(options.projectId, "TO11_PROJECT_ID");
 	// Default serving env: explicit option → `TO11_ENV` env var — the same
 	// `pick(option, "TO11_*")` resolution `apiKey`/`projectId` use (empty option
@@ -395,7 +324,7 @@ export function createClient<
 	// undefined in the browser, so only the explicit option can reach here.
 	if (isBrowser && options.apiKey !== undefined) {
 		throw new Error(
-			"[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.",
+			"[to11ai/sdk] Do not use `apiKey` in a browser — a to11 API key carries gateway access and must stay server-side (server, CLI, or backend job).",
 		);
 	}
 
@@ -422,23 +351,19 @@ export function createClient<
 		);
 	}
 
-	// Exactly one auth source after resolution.
-	const hasApiKey = apiKey !== undefined;
-	const hasGetAccessToken = getAccessToken !== undefined;
-	if (hasApiKey === hasGetAccessToken) {
+	// `apiKey` is the only auth source and is required.
+	if (apiKey === undefined) {
 		throw new Error(
-			"[to11ai/sdk] Provide exactly one of `apiKey` (or `TO11_API_KEY`) or `getAccessToken`.",
+			"[to11ai/sdk] An `apiKey` (or `TO11_API_KEY`) is required.",
 		);
 	}
 
-	const auth = hasApiKey
-		? ({ apiKey: apiKey as string } as const)
-		: ({ getAccessToken: getAccessToken as () => Promise<string> } as const);
+	const auth = { apiKey } as const;
 
-	const behaviorStore = new BehaviorStore({
-		initOverrides: options.behaviorOverrides,
-		env: processEnv,
-	});
+	// The SDK-behavior store (TO11-2100) still captures any server-delivered
+	// flags off responses, but the public `resolveBehavior` accessor is hidden
+	// for the 2.0 surface — kept internal so it can be re-exposed step by step.
+	const behaviorStore = new BehaviorStore({ env: processEnv });
 
 	const transport = new Transport({
 		baseUrl,
@@ -448,24 +373,18 @@ export function createClient<
 		behaviorStore,
 	});
 
-	const prompts = new PromptResource<F>(transport, options.cache, {
+	const prompts = new PromptResource<F>(transport, {
 		projectId,
 		env,
 		format: options.format,
 		onUnknownRole: options.onUnknownRole,
 	});
 	const projectEnvironments = new ProjectEnvironmentResource(transport);
-	const routingRules = new RoutingRulesResource(transport);
 
 	// ── Gateway observability context (session → conversation → turn) ──
-	// These build gateway auth headers, so they require a server-side apiKey +
-	// projectId; fail loudly rather than emit a broken header bag.
+	// These build gateway auth headers, so they require a projectId; fail loudly
+	// rather than emit a broken header bag.
 	const gatewayAuthContext = (): TurnAuthContext => {
-		if (apiKey === undefined) {
-			throw new Error(
-				"[to11ai/sdk] session()/turn()/openaiOptions() need an `apiKey` (or `TO11_API_KEY`) — gateway calls require a server-side key. In the browser use `getAccessToken` for control-plane calls only.",
-			);
-		}
 		if (projectId === undefined) {
 			throw new Error(
 				"[to11ai/sdk] session()/turn() need a `projectId` (or `TO11_PROJECT_ID`).",
@@ -496,11 +415,6 @@ export function createClient<
 		defaultBaseURL: string,
 		overrides?: T,
 	): ProviderClientOptions<T> => {
-		if (apiKey === undefined) {
-			throw new Error(
-				"[to11ai/sdk] openaiOptions()/anthropicOptions() need an `apiKey` (or `TO11_API_KEY`) — gateway calls require a server-side key. In the browser use `getAccessToken` for control-plane calls only.",
-			);
-		}
 		if (projectId === undefined) {
 			throw new Error(
 				"[to11ai/sdk] openaiOptions()/anthropicOptions() need a `projectId` (or `TO11_PROJECT_ID`) — it authenticates the gateway call via `x-to11-project-id`.",
@@ -530,12 +444,11 @@ export function createClient<
 	return {
 		prompts,
 		projectEnvironments,
-		routingRules,
-		resolveBehavior: (key, codedDefault) =>
-			behaviorStore.resolve(key, codedDefault),
 		apiKey,
+		baseUrl,
 		gatewayUrl,
 		projectId,
+		env,
 		session: (id) => new Session(gatewayAuthContext(), id),
 		conversation: (id) => clientDefaultSession().conversation(id),
 		turn: () => clientDefaultSession().turn(),

package/src/context.ts

@@ -49,10 +49,6 @@ 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.
@@ -105,7 +101,9 @@ export class Turn {
 			traceparent: this.traceparent,
 		};
 		if (prompt !== undefined) {
-			Object.assign(headers, gatewayPromptHeaders(provenanceOf(prompt)));
+			// gatewayPromptHeaders accepts a RenderedPrompt or a format-shaped
+			// result and unwraps `metadata` itself.
+			Object.assign(headers, gatewayPromptHeaders(prompt));
 		}
 		return headers;
 	}

package/src/errors.ts

@@ -342,60 +342,54 @@ export class PromptNotFoundError extends To11aiApiError {
 }
 
 /**
- * Reason payload for `EnvNotFoundError`.
+ * Thrown when the label supplied to `prompts.render()` does not resolve to an
+ * existing (active) label on the server. Surfaced from the server's
+ * `ENV_NOT_FOUND` code; `label` carries the rejected slug when the server
+ * echoes it.
  *
- * `source` discriminates the two failure modes (D2):
- *   - `"missing"` — no env was supplied at init OR at call time. Raised
- *     CLIENT-side, eagerly, before any request (R4 / AC4); `env` is absent.
- *   - `"unknown"` — an env was supplied but the server's registry has no
- *     such (active) env. Surfaced from the `ENV_NOT_FOUND` server code; `env`
- *     carries the rejected slug when the server echoes it.
+ * This is distinct from `MissingLabelError`, which is raised client-side when
+ * no label was supplied at all.
  */
-export interface EnvNotFoundReason {
-	env?: string;
-	source: "missing" | "unknown";
-}
-
-/**
- * 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`).
- *
- * The client-eager variant carries no `statusCode`/`errorCode` from the wire
- * (no request was made); it reports status `0` and errorCode `ENV_NOT_FOUND`
- * for a uniform catch surface.
- */
-export class EnvNotFoundError extends To11aiApiError {
-	readonly reason: EnvNotFoundReason;
+export class LabelNotFoundError extends To11aiApiError {
+	/** The label slug that could not be found, when the server echoes it. */
+	readonly label?: string;
 
 	constructor(
 		message: string,
-		reason: EnvNotFoundReason,
+		label: string | undefined,
 		details: unknown,
-		// Required (no misleading default): the client-eager `missing()` variant
-		// passes 0 (no HTTP call) and the transport mapper passes the real server
-		// status, so a hardcoded default would never reflect reality.
 		statusCode: number,
 	) {
+		// The wire code is unchanged (`ENV_NOT_FOUND`); only the SDK class name
+		// is label-oriented, decoupled from the server error code.
 		super(message, statusCode, "ENV_NOT_FOUND", details);
-		this.name = "EnvNotFoundError";
-		this.reason = reason;
+		this.name = "LabelNotFoundError";
+		this.label = label;
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 
-	/** 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.render(): none supplied at client init and none supplied per call. Pass `env` to createClient or render(slug, { env }).",
-			{ env, source: "missing" },
-			undefined,
-			0,
-		);
+	static is(err: unknown): err is LabelNotFoundError {
+		return err instanceof LabelNotFoundError;
+	}
+}
+
+/**
+ * Thrown CLIENT-side, eagerly (before any request), when `prompts.render()` is
+ * called but no label is resolvable at all: none supplied per call, and no
+ * client `env` (or `TO11_ENV`) to fall back to. A usage error, not a lookup
+ * failure — distinct from `LabelNotFoundError`.
+ */
+export class MissingLabelError extends To11aiError {
+	constructor(
+		message = "[to11ai/sdk] No label resolvable for prompts.render(): none supplied per call, and no client env (or TO11_ENV) to fall back to. Pass `label` to render(slug, { label }) or set `env` on createClient.",
+	) {
+		super(message);
+		this.name = "MissingLabelError";
+		Object.setPrototypeOf(this, new.target.prototype);
 	}
 
-	static is(err: unknown): err is EnvNotFoundError {
-		return err instanceof EnvNotFoundError;
+	static is(err: unknown): err is MissingLabelError {
+		return err instanceof MissingLabelError;
 	}
 }
 
@@ -480,44 +474,6 @@ export class PromptPolicyViolationError extends To11aiApiError {
 	}
 }
 
-/**
- * Reason payload for `AmbiguousEnvLabelsError`.
- *
- * Carried when the supplied env-label matched more than one candidate
- * version and the server cannot pick deterministically
- * (`AMBIGUOUS_ENV_LABELS`).
- */
-export interface AmbiguousEnvLabelsReason {
-	env?: string;
-	slug?: string;
-}
-
-/**
- * Thrown when the env→label resolution is ambiguous on the server
- * (`AMBIGUOUS_ENV_LABELS`) — the label matched multiple candidates and the
- * server declines to guess. Surfaces (rather than 500ing) so callers get a
- * typed, actionable error.
- */
-export class AmbiguousEnvLabelsError extends To11aiApiError {
-	readonly reason: AmbiguousEnvLabelsReason;
-
-	constructor(
-		message: string,
-		reason: AmbiguousEnvLabelsReason,
-		details?: unknown,
-		statusCode = 409,
-	) {
-		super(message, statusCode, "AMBIGUOUS_ENV_LABELS", details);
-		this.name = "AmbiguousEnvLabelsError";
-		this.reason = reason;
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-
-	static is(err: unknown): err is AmbiguousEnvLabelsError {
-		return err instanceof AmbiguousEnvLabelsError;
-	}
-}
-
 /**
  * Thrown when version create rejects the snapshot for a structural
  * reason — invalid variant params, malformed `when` clause, illegal

package/src/gateway.ts

@@ -73,29 +73,26 @@ export function gatewayAuthHeaders(
 }
 
 /**
- * Build prompt provenance headers from a resolved prompt (TO11-980 / R7).
+ * Build prompt provenance headers from a `render()` result (or a format-shaped
+ * result's `metadata`, unwrapped automatically).
  *
- * Emits the full provenance set for every gateway-bound LLM request that
- * 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 `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-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).
+ * No provenance header is required, and the gateway rejects empty header
+ * values — so each header is emitted only when its value is present and valid,
+ * and the function never throws:
+ *   - `x-to11-prompt-id` — a non-empty string.
+ *   - `x-to11-prompt-version` — a finite number (a non-number/NaN is dropped
+ *     rather than stringified to junk like `"[object Object]"`).
+ *   - `x-to11-release-id` — a non-empty `releaseId` (the offline-fallback path
+ *     can carry an explicit `null`, which is omitted).
+ *   - `x-to11-variant-name` — present IFF the resolved release was weighted.
+ *   - `x-to11-prompt-label` — the single label the prompt resolved through.
+ *   - `x-to11-prompt-slug` — the prompt's human-readable slug.
  *
- * 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).
+ * An input with no usable provenance yields an empty header bag — the same as
+ * a prompt-less `turn.headers()` call.
  *
  * @example
- * const result = await client.prompts.render(slug, { env: "prod" });
+ * const result = await client.prompts.render(slug, { label: "prod" });
  * const headers = gatewayPromptHeaders(result);
  */
 export interface GatewayPromptProvenance {
@@ -115,30 +112,38 @@ export interface GatewayPromptProvenance {
 }
 
 export function gatewayPromptHeaders(
-	prompt: GatewayPromptProvenance,
+	prompt: GatewayPromptProvenance | { metadata: GatewayPromptProvenance },
 ): Record<string, string> {
-	const headers: Record<string, string> = {
-		"x-to11-prompt-id": prompt.promptId,
-		"x-to11-prompt-version": String(prompt.version),
-	};
-	// 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;
+	// A format-shaped result carries provenance under `metadata`; unwrap it so
+	// the whole shaped result works, not just the bare provenance (mirrors the
+	// Python SDK).
+	const p = prompt != null && "metadata" in prompt ? prompt.metadata : prompt;
+	// No prompt provenance header is required, and the gateway rejects empty
+	// header values — so emit each one only when its value is present and valid,
+	// and never throw. An all-empty input just yields an empty header bag (the
+	// same as a prompt-less `turn.headers()` call).
+	const headers: Record<string, string> = {};
+	if (p == null) return headers;
+	if (typeof p.promptId === "string" && p.promptId.length > 0) {
+		headers["x-to11-prompt-id"] = p.promptId;
+	}
+	// A non-finite/non-number version would stringify to junk (e.g. NaN or
+	// "[object Object]"); only emit a real finite number.
+	if (typeof p.version === "number" && Number.isFinite(p.version)) {
+		headers["x-to11-prompt-version"] = String(p.version);
+	}
+	if (typeof p.releaseId === "string" && p.releaseId.length > 0) {
+		headers["x-to11-release-id"] = p.releaseId;
 	}
-	if (typeof prompt.variantName === "string" && prompt.variantName.length > 0) {
-		headers["x-to11-variant-name"] = prompt.variantName;
+	// variantName is present IFF the resolved release was weighted.
+	if (typeof p.variantName === "string" && p.variantName.length > 0) {
+		headers["x-to11-variant-name"] = p.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 (typeof p.label === "string" && p.label.length > 0) {
+		headers["x-to11-prompt-label"] = p.label;
 	}
-	// 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;
+	if (typeof p.slug === "string" && p.slug.length > 0) {
+		headers["x-to11-prompt-slug"] = p.slug;
 	}
 	return headers;
 }
@@ -175,13 +180,25 @@ export interface OpenAIToolCall {
 	function: { name: string; arguments: string };
 }
 
-/** OpenAI Chat Completions `messages[]` entry. */
-export interface OpenAIChatMessage {
-	role: "system" | "developer" | "user" | "assistant" | "tool";
-	content?: string | null;
-	tool_calls?: OpenAIToolCall[];
-	tool_call_id?: string;
-}
+/**
+ * OpenAI Chat Completions `messages[]` entry — a per-role discriminated union
+ * matching what Chat Completions requires for each role, so an
+ * `OpenAIChatMessage[]` is structurally assignable to the `openai` package's
+ * `ChatCompletionMessageParam[]` (a `render({ format: "openai" })` result spreads
+ * straight into `openai.chat.completions.create({ messages })` with no cast).
+ * The SDK carries no dependency on the `openai` package — this only mirrors its
+ * shape. (Assignability is regression-guarded in `gateway.provider-types.test.ts`.)
+ */
+export type OpenAIChatMessage =
+	| { role: "system"; content: string }
+	| { role: "developer"; content: string }
+	| { role: "user"; content: string }
+	| {
+			role: "assistant";
+			content?: string | null;
+			tool_calls?: OpenAIToolCall[];
+	  }
+	| { role: "tool"; tool_call_id: string; content: string };
 
 /** Anthropic Messages `tools[]` entry. */
 export interface AnthropicTool {
@@ -405,24 +422,37 @@ export function toOpenAIMessages(
 			return;
 		}
 		if (message.role === "assistant") {
-			const msg: OpenAIChatMessage = {
-				role: "assistant",
-				content: message.content ?? null,
-			};
-			if (message.toolCalls != null && message.toolCalls.length > 0) {
-				msg.tool_calls = message.toolCalls.map((call) => ({
-					id: requireToolCallId(call.id),
-					type: "function",
-					function: {
-						name: call.name,
-						arguments: JSON.stringify(call.arguments),
-					},
-				}));
-			}
-			out.push(msg);
+			const content = message.content ?? null;
+			out.push(
+				message.toolCalls != null && message.toolCalls.length > 0
+					? {
+							role: "assistant",
+							content,
+							tool_calls: message.toolCalls.map((call) => ({
+								id: requireToolCallId(call.id),
+								type: "function",
+								function: {
+									name: call.name,
+									arguments: JSON.stringify(call.arguments),
+								},
+							})),
+						}
+					: { role: "assistant", content },
+			);
 			return;
 		}
-		out.push({ role: message.role, content: message.content ?? "" });
+		// Remaining plain-text roles: `system` | `developer` | `user`. Push a
+		// literal-role object per branch so each element lands on a single union
+		// member (a union-typed `role` wouldn't be assignable to the discriminated
+		// ChatCompletionMessageParam).
+		const content = message.content ?? "";
+		if (message.role === "user") {
+			out.push({ role: "user", content });
+		} else if (message.role === "developer") {
+			out.push({ role: "developer", content });
+		} else {
+			out.push({ role: "system", content });
+		}
 	});
 	return out;
 }