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

package/dist/prompts/resource.js

@@ -1,11 +1,13 @@
 // src/prompts/resource.ts
-import { z } from "zod";
-import { EnvNotFoundError, To11aiNetworkError } from "../errors";
+import {
+  MissingLabelError,
+  To11aiApiError,
+  To11aiNetworkError
+} from "../errors";
 import { zResolvedPrompt } from "../generated/zod.gen";
-import { buildRenderCacheKey, PromptCache } from "./cache";
 import { shapePrompt } from "./shape";
 import { ENV_SLUG_REGEX } from "./types";
-var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: z.enum(["single", "weighted"]).optional() });
+var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true });
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
     throw new Error("API returned success but data is null");
@@ -85,14 +87,12 @@ function buildLabelEventsQuery(input) {
 
 class PromptResource {
   transport;
-  cache;
   projectId;
   env;
   format;
   onUnknownRole;
-  constructor(transport, cacheConfig, config) {
+  constructor(transport, config) {
     this.transport = transport;
-    this.cache = new PromptCache(cacheConfig);
     this.projectId = config?.projectId;
     this.env = config?.env;
     this.format = config?.format;
@@ -187,21 +187,15 @@ class PromptResource {
     if (this.projectId === undefined || this.projectId.trim() === "") {
       throw new Error("[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).");
     }
-    const env = options.env ?? this.env;
-    if (env === undefined) {
-      throw EnvNotFoundError.missing();
+    const label = options.label ?? this.env;
+    if (label === undefined) {
+      throw new MissingLabelError;
     }
-    if (!ENV_SLUG_REGEX.test(env)) {
-      throw new Error(`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`);
+    if (!ENV_SLUG_REGEX.test(label)) {
+      throw new Error(`[to11ai/sdk] \`label\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(label)}`);
     }
-    const { subject, variables, cache: useCache = true, fallback } = options;
-    const cacheKey = buildRenderCacheKey(this.projectId, slug, env, subject, variables);
-    if (useCache) {
-      const cached = this.cache.get(cacheKey);
-      if (cached)
-        return structuredClone(cached);
-    }
-    const body = { slug, labels: [env] };
+    const { subject, variables, fallback } = options;
+    const body = { slug, labels: [label] };
     if (subject !== undefined)
       body.subject = subject;
     if (variables !== undefined)
@@ -212,15 +206,10 @@ class PromptResource {
         decode: (data) => zResolvedPromptEnvelope.parse(data)
       });
       const raw = unwrap(envelope);
-      const result = normalizeResolvedEnvelope(raw, slug);
-      const isWeighted = raw.strategy === "weighted" || result.variantName !== undefined;
-      const cacheable = !(isWeighted && subject === undefined);
-      if (useCache && cacheable) {
-        this.cache.set(cacheKey, structuredClone(result));
-      }
-      return result;
+      return normalizeResolvedEnvelope(raw, slug);
     } catch (err) {
-      if (err instanceof To11aiNetworkError && fallback !== undefined) {
+      const transient = err instanceof To11aiNetworkError || err instanceof To11aiApiError && err.statusCode >= 500;
+      if (transient && fallback !== undefined) {
         return liftFallbackToRendered(fallback, slug);
       }
       throw err;

package/dist/prompts/shape.d.ts

@@ -52,5 +52,5 @@ export interface AnthropicRenderedPrompt {
 export type RenderResult<F extends RenderFormat | undefined> = F extends "openai" ? OpenAiRenderedPrompt : F extends "anthropic" ? AnthropicRenderedPrompt : RenderedPrompt;
 export declare function shapeOpenAI(prompt: RenderedPrompt, options?: ConvertMessagesOptions): OpenAiRenderedPrompt;
 export declare function shapeAnthropic(prompt: RenderedPrompt, options?: ConvertMessagesOptions): AnthropicRenderedPrompt;
-/** Shape a fetched prompt for `format`, or return it neutral when unset. */
+/** Shape a rendered prompt for `format`, or return it neutral when unset. */
 export declare function shapePrompt(prompt: RenderedPrompt, format: RenderFormat | undefined, options?: ConvertMessagesOptions): RenderedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt;

package/dist/prompts/types.d.ts

@@ -9,13 +9,12 @@ export type PromptStatus = Prompt["status"];
 export type PromptVersion = GenPromptVersion;
 export type PromptFormat = PromptVersion["format"];
 export type PromptLabelPointer = GenPromptLabelPointer;
-export type TextChatRole = "system" | "user" | "assistant" | "developer";
-export interface TextChatMessage {
-    role: TextChatRole;
+export type ChatRole = "system" | "user" | "assistant" | "developer";
+export interface ChatMessage {
+    role: ChatRole;
     content: string;
     disabled?: boolean;
 }
-export type ChatMessage = TextChatMessage;
 export type RenderedChatMessage = GenRenderedChatPrompt["messages"][number];
 /** Provider shape for `prompts.render()` output. Omit for the neutral result. */
 export type RenderFormat = "openai" | "anthropic";
@@ -118,6 +117,13 @@ export interface ListPromptLabelsInput {
     promptId: string;
 }
 export type ListPromptLabelsResult = PromptLabelPointer[];
+/**
+ * Slug rule for a `render()` label — lowercase-kebab, 1-63 chars. Env slugs are
+ * a special case of a label value, so labels are held to the same strict rule
+ * (no uppercase, no underscores): a label is a routing key, and case-insensitive
+ * routing keys invite silent "production" vs "Production" mismatches. Intentionally
+ * strict — do not loosen.
+ */
 export declare const ENV_SLUG_REGEX: RegExp;
 export type BlockRenderRecord = Record<string, "rendered" | "dimmed">;
 export interface RenderedPrompt {
@@ -164,19 +170,17 @@ export interface RenderedPrompt {
      */
     toolChoice?: NonNullable<ResolvedPrompt["toolChoice"]>;
 }
-export type ResolvedPromptEnvelope = GenResolvedPrompt & {
-    /** Active release strategy. Used to decide weighted-no-subject cache bypass (D8). */
-    strategy?: "single" | "weighted";
-};
+export type ResolvedPromptEnvelope = GenResolvedPrompt;
 export interface RenderOptions {
-    /** Serving environment for this call; overrides the client default. */
-    env?: string;
+    /**
+     * Label to resolve this call's prompt version; overrides the client default.
+     * When omitted, falls back to the client's `env` (env is a label value).
+     */
+    label?: string;
     /** Stable id so a weighted release sends the same caller to the same variant. */
     subject?: string;
     variables?: Record<string, unknown>;
-    /** Set false to bypass the LRU cache for this call. Default: true */
-    cache?: boolean;
-    /** Prompt served if the API is unreachable on a network error and cache is empty. */
+    /** Prompt served if the API is unreachable on a network error. */
     fallback?: RenderedPrompt;
     /** Provider shape for this call's output; overrides the client default. */
     format?: RenderFormat;

package/dist/transport.d.ts

@@ -1,11 +1,7 @@
 import type { BehaviorStore } from "./behaviors/store";
-export type AuthConfig = {
+export interface AuthConfig {
     readonly apiKey: string;
-    readonly getAccessToken?: never;
-} | {
-    readonly getAccessToken: () => Promise<string>;
-    readonly apiKey?: never;
-};
+}
 export interface TransportConfig {
     readonly baseUrl: string;
     readonly auth: AuthConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@to11ai/sdk",
-	"version": "2.0.0-rc.3",
+	"version": "2.0.0-rc.4",
 	"license": "MPL-2.0",
 	"repository": {
 		"type": "git",
@@ -44,14 +44,6 @@
 			"require": "./dist/projectEnvironments/resource.cjs",
 			"default": "./dist/projectEnvironments/resource.js"
 		},
-		"./routingRules": {
-			"types": "./dist/routingRules/resource.d.ts",
-			"bun": "./src/routingRules/resource.ts",
-			"deno": "./src/routingRules/resource.ts",
-			"import": "./dist/routingRules/resource.js",
-			"require": "./dist/routingRules/resource.cjs",
-			"default": "./dist/routingRules/resource.js"
-		},
 		"./errors": {
 			"types": "./dist/errors.d.ts",
 			"bun": "./src/errors.ts",
@@ -75,8 +67,8 @@
 	"scripts": {
 		"build": "bun run build:clean && bun run build:esm && bun run build:cjs && bun run build:types",
 		"build:clean": "rm -rf dist",
-		"build:esm": "bun build src/client.ts src/prompts/resource.ts src/projectEnvironments/resource.ts src/routingRules/resource.ts src/errors.ts src/gateway.ts --outdir dist --target node --format esm --external '*'",
-		"build:cjs": "bun build src/client.ts src/prompts/resource.ts src/projectEnvironments/resource.ts src/routingRules/resource.ts src/errors.ts src/gateway.ts --outdir dist --target node --format cjs --external '*' --entry-naming '[dir]/[name].cjs'",
+		"build:esm": "bun build src/client.ts src/prompts/resource.ts src/projectEnvironments/resource.ts src/errors.ts src/gateway.ts --outdir dist --target node --format esm --external '*'",
+		"build:cjs": "bun build src/client.ts src/prompts/resource.ts src/projectEnvironments/resource.ts src/errors.ts src/gateway.ts --outdir dist --target node --format cjs --external '*' --entry-naming '[dir]/[name].cjs'",
 		"build:types": "tsc -p tsconfig.build.json",
 		"prepack": "bun run build",
 		"codegen": "openapi-ts",

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