@to11ai/sdk 1.1.0 → 2.0.0-rc.10

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": "1.1.0",
+	"version": "2.0.0-rc.10",
 	"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",
@@ -90,10 +82,12 @@
 		"format": "biome format --write ."
 	},
 	"devDependencies": {
+		"@anthropic-ai/sdk": "^0.39.0",
 		"@biomejs/biome": "2.4.16",
 		"@hey-api/openapi-ts": "0.98.2",
 		"@opentelemetry/api": "^1.9.1",
 		"@types/bun": "^1.3.14",
+		"openai": "^4.67.0",
 		"typescript": "^6.0.3"
 	},
 	"dependencies": {

package/src/client.ts

@@ -1,47 +1,46 @@
 import { BehaviorStore } from "./behaviors/store";
+import { DEFAULT_API_URL, DEFAULT_GATEWAY_URL } from "./config";
+import {
+	type Conversation,
+	Session,
+	type Turn,
+	type TurnAuthContext,
+} 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 } from "./prompts/types";
-import { RoutingRulesResource } from "./routingRules/resource";
+import {
+	ENV_SLUG_REGEX,
+	type RenderFormat,
+	type UnknownRoleMode,
+} from "./prompts/types";
 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,
 	To11aiNetworkError,
 	To11aiRateLimitError,
 	To11aiValidationError,
+	UnknownRoleError,
 } from "./errors";
-export type { GatewayAuthOptions } from "./gateway";
+export type { ConvertMessagesOptions, GatewayAuthOptions } from "./gateway";
 export { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
 export type {
 	ArchiveProjectEnvironmentInput,
@@ -60,134 +59,204 @@ 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";
-// TO11-980 (S9): env-aware fetch() surface types at the package entrypoint (AC9).
+export type {
+	AnthropicRenderedPrompt,
+	OpenAiRenderedPrompt,
+	PromptConfig,
+	PromptMetadata,
+	RenderResult,
+} from "./prompts/shape";
+// TO11-980 (S9): env-aware render() surface types at the package entrypoint (AC9).
 export type {
 	BlockRenderRecord,
-	DeveloperRole,
-	FetchedPrompt,
-	FetchPromptOptions,
 	RenderedChatMessage,
 	RenderedPrompt,
-	ResolvedPrompt,
-	ResolvedPromptEnvelope,
+	RenderFormat,
+	RenderOptions,
+	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";
-
-// ─── Auth option shapes ────────────────────────────────────────────────────
-
-interface ServerAuthOptions {
-	/** API key for server-side use. Must not be used in browser contexts. */
-	apiKey: string;
-	getAccessToken?: never;
-}
-
-interface BrowserAuthOptions {
-	/** Token callback for browser / edge contexts — avoids static secrets. */
-	getAccessToken: () => Promise<string>;
-	apiKey?: never;
-}
-
-type AuthOptions = ServerAuthOptions | BrowserAuthOptions;
 
 // ─── Client options ────────────────────────────────────────────────────────
 
-export type ClientOptions = AuthOptions & {
-	baseUrl: string;
+export interface ClientOptions {
+	/**
+	 * Control-plane base URL. Precedence: this option → `TO11_API_URL` env →
+	 * `https://api.to11.ai`.
+	 */
+	baseUrl?: string;
+	/**
+	 * Data-plane gateway URL (the app's provider-client `baseURL`). Precedence:
+	 * this option → `TO11_GATEWAY_URL` env → `https://gw.to11.ai`.
+	 */
+	gatewayUrl?: string;
+	/**
+	 * 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;
+	/**
+	 * Provider API key (BYOK) carried by `openaiOptions()` / `anthropicOptions()`
+	 * as the provider client's `apiKey`, so a BYOK call is a single
+	 * `new OpenAI(to11.openaiOptions())`. When omitted, those helpers fall back to
+	 * the to11 `apiKey` as a placeholder (the managed / server-side-credential
+	 * path). Option only — no env fallback. Whether the gateway actually uses this
+	 * key depends on the provider's passthrough mode; otherwise the project's
+	 * stored credential wins.
+	 */
+	providerApiKey?: string;
 	/**
-	 * Project the client is bound to (TO11-980 / S9). Required for the
-	 * env-aware `prompts.fetch(slug, …)` surface, which builds the
-	 * project-scoped resolve path from it. Validated non-empty at
-	 * construction. The deprecated `prompts.resolve()` keeps its per-call
-	 * `projectId` and ignores this.
+	 * Project the client is bound to. Precedence: this option → `TO11_PROJECT_ID`
+	 * env. Required for `prompts.render()` and the gateway context helpers.
 	 */
 	projectId?: string;
 	/**
-	 * Default serving environment for `prompts.fetch(slug)` (TO11-980 / S9,
-	 * Style-A). When set, every `fetch()` call inherits it unless overridden
-	 * per call. Validated eagerly against the project-environments registry
-	 * rule (lowercase-kebab, `^[a-z0-9-]{1,63}$`): empty / whitespace-only /
-	 * uppercase / 64+-char values throw at construction with a loud
-	 * `[to11ai/sdk]` message before any request hits the wire.
+	 * Default serving environment for `prompts.render(slug)`, inherited by every
+	 * render unless overridden per call. Precedence: this option → `TO11_ENV`
+	 * env. Validated eagerly against the project-environments slug rule
+	 * (`^[a-z0-9-]{1,63}$`).
 	 */
 	env?: string;
-	/** LRU cache configuration for resolve(). Defaults: ttlSeconds=300, maxEntries=100 */
-	cache?: CacheConfig;
+	/**
+	 * Default provider shape for `prompts.render()` output (`"openai"` |
+	 * `"anthropic"`). Omit for the neutral result. Per-call override allowed.
+	 */
+	format?: RenderFormat;
+	/**
+	 * Default policy for a message with an unrecognized role while shaping
+	 * `render({ format })` output: `"drop"` (default, silent), `"warn"` (drop +
+	 * `console.warn`), or `"error"` (throw `UnknownRoleError`). Per-call override
+	 * via `render(slug, { onUnknownRole })`.
+	 */
+	onUnknownRole?: UnknownRoleMode;
 	/** 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),
-	 * keyed by namespaced flag key (e.g. `{ "sdk.retry-v2": true }`). These take
-	 * precedence over server-delivered values and the SDK's coded defaults. For
-	 * the same flag key, an init option here wins over a `TO11_SDK_BEHAVIOR_*`
-	 * environment variable. Published-SDK only — no LaunchDarkly involved.
-	 */
-	behaviorOverrides?: Record<string, unknown>;
+}
+
+// ─── Provider-client options (openaiOptions / anthropicOptions) ─────────────
+
+/**
+ * Overrides accepted by `openaiOptions()` / `anthropicOptions()`. The three
+ * known fields are merged (`apiKey` / `baseURL` override; `defaultHeaders`
+ * shallow-merges over the tenant-auth headers, caller wins); any other keys —
+ * `timeout`, `maxRetries`, `fetch`, … — pass through untouched to the provider
+ * client, so `new OpenAI(to11.openaiOptions({ apiKey, timeout }))` needs no
+ * outer spread.
+ */
+export interface ProviderClientOverrides {
+	apiKey?: string;
+	baseURL?: string;
+	defaultHeaders?: Record<string, string>;
+}
+
+/**
+ * The spread-ready result of `openaiOptions()` / `anthropicOptions()`: the three
+ * managed fields plus whatever passthrough keys the caller supplied (their types
+ * preserved), so it drops straight into `new OpenAI(...)` / `new Anthropic(...)`.
+ */
+export type ProviderClientOptions<
+	T extends ProviderClientOverrides = ProviderClientOverrides,
+> = Omit<T, "apiKey" | "baseURL" | "defaultHeaders"> & {
+	baseURL: string;
+	apiKey: string;
+	defaultHeaders: Record<string, string>;
 };
 
 // ─── Client interface ──────────────────────────────────────────────────────
 
-export interface To11aiClient {
-	readonly prompts: PromptResource;
+export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
+	readonly prompts: PromptResource<F>;
 	readonly projectEnvironments: ProjectEnvironmentResource;
-	readonly routingRules: RoutingRulesResource;
+	/** 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;
+	/**
+	 * Resolved project id (option → `TO11_PROJECT_ID`); `undefined` when none is
+	 * configured. Read-only, for your own logging / manual headers — `prompts.*`
+	 * already default to it, so you don't need to pass it back into calls.
+	 */
+	readonly projectId: string | undefined;
 	/**
-	 * 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.
+	 * Resolved default serving environment (option → `TO11_ENV`); `undefined`
+	 * when none is configured. `prompts.render()` already defaults to it.
 	 */
-	readonly resolveBehavior: <T>(key: string, codedDefault: T) => T;
+	readonly env: string | undefined;
+	/** A new session (unit of work). Pass an id to group telemetry by your own id. */
+	session(id?: string): Session;
+	/**
+	 * A conversation in the client's default session (for side / parallel agents).
+	 *
+	 * @example Two agents under one session
+	 * const research = to11.conversation();   // a separate thread from to11.turn()'s default
+	 * const res = await openai.chat.completions.create(
+	 *   { ...researchPrompt.config, messages },
+	 *   { headers: research.turn().headers(researchPrompt) },
+	 * );
+	 */
+	conversation(id?: string): Conversation;
+	/** A turn in the client's default session + default conversation. */
+	turn(): Turn;
+	/**
+	 * Spread-ready options for `new OpenAI(...)` targeting the gateway:
+	 * `{ baseURL, apiKey, defaultHeaders }` (baseURL carries `/v1`). `defaultHeaders`
+	 * holds the static tenant auth, so the client authenticates on its own; add
+	 * `turn().headers(prompt)` per call for trace + prompt provenance. Pass
+	 * `overrides` to change `apiKey`/`baseURL`, merge extra `defaultHeaders`, or
+	 * forward any other provider-SDK option (`timeout`, …).
+	 *
+	 * @example
+	 * const openai = new OpenAI(to11.openaiOptions());
+	 * @example BYOK + a provider-SDK option, no outer spread
+	 * const openai = new OpenAI(to11.openaiOptions({ apiKey: MY_KEY, timeout: 60_000 }));
+	 */
+	openaiOptions<T extends ProviderClientOverrides = ProviderClientOverrides>(
+		overrides?: T,
+	): ProviderClientOptions<T>;
+	/**
+	 * Spread-ready options for `new Anthropic(...)` targeting the gateway root
+	 * (the Anthropic SDK appends `/v1/messages` itself). Same shape and merge
+	 * rules as {@link To11aiClient.openaiOptions}.
+	 */
+	anthropicOptions<T extends ProviderClientOverrides = ProviderClientOverrides>(
+		overrides?: T,
+	): ProviderClientOptions<T>;
 }
 
 // ─── Factory ───────────────────────────────────────────────────────────────
 
 /**
- * Create a to11ai SDK client.
+ * Create a to11ai SDK client. Resolution precedence differs per option:
+ *  - URLs (`baseUrl` / `gatewayUrl`) — option → env var → built-in default.
+ *  - `apiKey` / `projectId` — option → env var (no default).
+ *  - `env` / `format` — option only.
+ * 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";
+ * import OpenAI from "openai";
  *
- * Auth mode is inferred from options:
- *  - `apiKey`          → server-side; rejected in browser contexts.
- *  - `getAccessToken`  → browser-safe; token fetched per request.
+ * const to11   = createClient({ env: "prod", format: "openai" });
+ * const openai = new OpenAI(to11.openaiOptions());
+ * const prompt = await to11.prompts.render("weather-concierge", { variables: { city: "NYC" } });
+ * const res = await openai.chat.completions.create(
+ *   { ...prompt.config, messages: prompt.messages },
+ *   { headers: to11.turn().headers(prompt) },
+ * );
  */
-export function createClient(options: ClientOptions): To11aiClient {
+export function createClient<
+	const F extends RenderFormat | undefined = undefined,
+>(
+	options: Omit<ClientOptions, "format"> & { format?: F } = {},
+): To11aiClient<F> {
 	const isDomBrowser =
 		typeof globalThis === "object" &&
 		typeof (globalThis as { document?: unknown }).document !== "undefined";
@@ -206,86 +275,192 @@ export function createClient(options: ClientOptions): To11aiClient {
 			(!isBunMainThread &&
 				typeof workerLikeGlobal.postMessage === "function" &&
 				typeof workerLikeGlobal.onmessage !== "undefined"));
+	const isBrowser = isDomBrowser || isWorkerBrowser;
 
-	if ((isDomBrowser || isWorkerBrowser) && options.apiKey !== undefined) {
+	// Env vars are read ONLY in a non-browser context, so the published browser
+	// bundle never touches `process.env`; explicit options apply everywhere.
+	const processEnv =
+		!isBrowser &&
+		typeof process !== "undefined" &&
+		typeof process.env === "object"
+			? process.env
+			: undefined;
+
+	// Resolve each value: explicit option → env var → default. `pick` trims and
+	// treats empty as absent, so an empty option or env value falls through.
+	const pick = (
+		opt: string | undefined,
+		envKey: string,
+	): string | undefined => {
+		const fromOpt = opt?.trim();
+		if (fromOpt) return fromOpt;
+		const fromEnv = processEnv?.[envKey]?.trim();
+		return fromEnv ? fromEnv : undefined;
+	};
+
+	const baseUrl = pick(options.baseUrl, "TO11_API_URL") ?? DEFAULT_API_URL;
+	// The gateway root (host, no version path). Normalize away a trailing slash
+	// and a trailing `/v1` so both the root form (`https://gw.to11.ai`) and the
+	// older `/v1` form resolve identically — the provider helpers add the path
+	// each SDK expects.
+	const gatewayUrl = (
+		pick(options.gatewayUrl, "TO11_GATEWAY_URL") ?? DEFAULT_GATEWAY_URL
+	)
+		.replace(/\/+$/, "")
+		.replace(/\/v1$/, "");
+	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
+	// or empty env var trims to absent). An explicit empty option is rejected by
+	// the dedicated guard below (mirroring `apiKey`/`projectId`); a non-empty but
+	// malformed value fails the `ENV_SLUG_REGEX` check.
+	const env = pick(options.env, "TO11_ENV");
+	// Provider (BYOK) key — option only, no env fallback (which provider's env
+	// var is ambiguous). Empty trims to absent so it falls back to the placeholder.
+	const providerApiKey = options.providerApiKey?.trim() || undefined;
+
+	// A browser must never carry a static API key. `processEnv` is already
+	// 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).",
 		);
 	}
 
+	// Explicit empty credentials are a misconfiguration — reject loudly.
 	if (options.apiKey !== undefined && options.apiKey.trim() === "") {
 		throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
 	}
-
-	// R0: validate `projectId` eagerly when supplied (loud throw). An empty /
-	// whitespace-only value is a misconfiguration; reject before any request.
 	if (options.projectId !== undefined && options.projectId.trim() === "") {
 		throw new Error(
 			"[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.",
 		);
 	}
-
-	// R1: validate the init-time `env` against the project-environments
-	// registry rule (stricter than gatewayAuthHeaders' empty-only check) so a
-	// malformed env fails locally rather than round-tripping to ENV_NOT_FOUND.
-	if (options.env !== undefined && !ENV_SLUG_REGEX.test(options.env)) {
+	if (options.env !== undefined && options.env.trim() === "") {
 		throw new Error(
-			`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`,
+			"[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.",
 		);
 	}
 
-	// TypeScript's union type prevents callers from providing both, but JS consumers can.
-	// Perform an explicit XOR check at runtime to catch the case where both are supplied.
-	const hasApiKey = options.apiKey !== undefined;
-	const hasGetAccessToken = options.getAccessToken !== undefined;
-	const getAccessToken = options.getAccessToken;
+	// Validate the init-time `env` against the project-environments slug rule so
+	// a malformed env fails locally rather than round-tripping to ENV_NOT_FOUND.
+	if (env !== undefined && !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 (hasApiKey === hasGetAccessToken) {
+	// `apiKey` is the only auth source and is required.
+	if (apiKey === undefined) {
 		throw new Error(
-			"[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).",
+			"[to11ai/sdk] An `apiKey` (or `TO11_API_KEY`) is required.",
 		);
 	}
 
-	const auth =
-		options.apiKey !== undefined
-			? ({ apiKey: options.apiKey } as const)
-			: ({ getAccessToken: getAccessToken as () => Promise<string> } as const);
+	const auth = { apiKey } as const;
 
-	// SDK-behavior store (TO11-2100). Env-var overrides (`TO11_SDK_BEHAVIOR_*`)
-	// are read ONLY in a non-browser context so the published browser bundle
-	// never touches `process.env`; init-option overrides apply everywhere.
-	const isBrowser = isDomBrowser || isWorkerBrowser;
-	const processEnv =
-		!isBrowser &&
-		typeof process !== "undefined" &&
-		typeof process.env === "object"
-			? process.env
-			: undefined;
-	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: options.baseUrl,
+		baseUrl,
 		auth,
 		timeoutMs: options.timeoutMs,
 		maxRetries: options.maxRetries,
 		behaviorStore,
 	});
 
-	const prompts = new PromptResource(transport, options.cache, {
-		projectId: options.projectId,
-		env: options.env,
+	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 projectId; fail loudly
+	// rather than emit a broken header bag.
+	const gatewayAuthContext = (): TurnAuthContext => {
+		if (projectId === undefined) {
+			throw new Error(
+				"[to11ai/sdk] session()/turn() need a `projectId` (or `TO11_PROJECT_ID`).",
+			);
+		}
+		return env !== undefined
+			? { apiKey, projectId, env }
+			: { apiKey, projectId };
+	};
+
+	let defaultSession: Session | undefined;
+	const clientDefaultSession = (): Session => {
+		if (defaultSession === undefined) {
+			defaultSession = new Session(gatewayAuthContext());
+		}
+		return defaultSession;
+	};
+
+	// OpenAI's SDK convention puts `/v1` in `baseURL`; the Anthropic SDK appends
+	// `/v1/messages` itself, so it takes the gateway root. Both point at the same
+	// gateway; only the base differs per provider convention. The result is a
+	// spread-ready provider-client options object: managed fields (baseURL/apiKey/
+	// defaultHeaders) are computed+merged, and any other override key passes
+	// through untouched to the provider SDK.
+	const gatewayClientOptions = <
+		T extends ProviderClientOverrides = ProviderClientOverrides,
+	>(
+		defaultBaseURL: string,
+		overrides?: T,
+	): ProviderClientOptions<T> => {
+		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`.",
+			);
+		}
+		// Static tenant auth for the provider client's defaultHeaders; per-call
+		// trace + prompt provenance still come from `turn().headers(prompt)`.
+		const authHeaders = gatewayAuthHeaders(
+			env !== undefined ? { apiKey, projectId, env } : { apiKey, projectId },
+		);
+		const {
+			apiKey: overrideApiKey,
+			baseURL: overrideBaseURL,
+			defaultHeaders: overrideHeaders,
+			...passthrough
+		} = overrides ?? ({} as T);
+		return {
+			...passthrough,
+			baseURL: overrideBaseURL ?? defaultBaseURL,
+			// Provider (BYOK) key when supplied, else the to11 key as a placeholder
+			// (the managed / server-side-credential path).
+			apiKey: overrideApiKey ?? providerApiKey ?? apiKey,
+			defaultHeaders: { ...authHeaders, ...overrideHeaders },
+		} as ProviderClientOptions<T>;
+	};
 
 	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(),
+		openaiOptions: <
+			T extends ProviderClientOverrides = ProviderClientOverrides,
+		>(
+			overrides?: T,
+		) => gatewayClientOptions(`${gatewayUrl}/v1`, overrides),
+		anthropicOptions: <
+			T extends ProviderClientOverrides = ProviderClientOverrides,
+		>(
+			overrides?: T,
+		) => gatewayClientOptions(gatewayUrl, overrides),
 	};
 }