@to11ai/sdk 1.1.0 → 2.0.0-rc.1

package/src/prompts/cache.ts

@@ -9,7 +9,7 @@ export interface CacheConfig {
 
 /**
  * The cache stores either a legacy `resolve()` result or an enriched
- * `fetch()` result. Both are JSON-cloneable; the cache is shape-agnostic.
+ * `render()` result. Both are JSON-cloneable; the cache is shape-agnostic.
  */
 export type CacheableResolved = ResolvedPrompt | FetchedPrompt;
 
@@ -44,7 +44,7 @@ export function buildCacheKey(
 }
 
 /**
- * Build a cache key for an env-aware `fetch()` call.
+ * Build a cache key for an env-aware `render()` call.
  *
  * Folds in `env` and `subject` ON TOP of the base
  * project/slug/labels/variables key so two calls that differ only by
@@ -64,12 +64,9 @@ export function buildFetchCacheKey(
 	env: string,
 	subject?: string,
 	variables?: Record<string, unknown>,
-	developerRole?: string,
 ): string {
 	const base = buildCacheKey(projectId, slug, [env], variables);
-	// `developerRole` partitions the cache; coalesce the default so omitted and
-	// `"user"` (the documented default) share one entry, not two.
-	return `fetch|${base}|${JSON.stringify(env)}|${JSON.stringify(subject ?? null)}|${JSON.stringify(developerRole ?? "user")}`;
+	return `fetch|${base}|${JSON.stringify(env)}|${JSON.stringify(subject ?? null)}`;
 }
 
 function sortObjectKeys(obj: unknown): unknown {

package/src/prompts/resource.ts

@@ -4,6 +4,12 @@ import { zResolvedPrompt } from "../generated/zod.gen";
 import type { ApiEnvelope, Transport } from "../transport";
 import type { CacheConfig } from "./cache";
 import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
+import type {
+	AnthropicRenderedPrompt,
+	OpenAiRenderedPrompt,
+	RenderResult,
+} from "./shape";
+import { shapePrompt } from "./shape";
 import type {
 	ArchivePromptInput,
 	ArchivePromptResult,
@@ -40,10 +46,13 @@ import type {
 	PaginatedResult,
 	RenderedChatMessage,
 	RenderedPrompt,
+	RenderFormat,
+	RenderOptions,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
 	ResolvePromptInput,
 	ResolvePromptResult,
+	UnknownRoleMode,
 	UpdateProjectPromptLabelInput,
 	UpdateProjectPromptLabelResult,
 	UpdatePromptInput,
@@ -120,11 +129,12 @@ const zResolvedPromptLegacy = zResolvedPrompt.pick({
 	promptId: true,
 	versionId: true,
 	version: true,
-	labels: true,
+	label: true,
 	contentHash: true,
 	rendered: true,
 	tools: true,
 	toolChoice: true,
+	modelConfig: true,
 });
 
 const zResolvedPromptEnvelope = zResolvedPrompt
@@ -177,8 +187,9 @@ function normalizeResolvedEnvelope(
 		promptId: raw.promptId,
 		versionId: raw.versionId,
 		contentHash: raw.contentHash,
-		labels: raw.labels,
+		label: raw.label,
 		rendered: raw.rendered,
+		modelConfig: provenance.modelConfig,
 	};
 	// `tools` is present IFF the resolved version declares tool definitions; the
 	// wire may send `null` (or omit it) — normalize both to absent so callers
@@ -209,7 +220,7 @@ function normalizeResolvedEnvelope(
 
 /**
  * Lift a caller-supplied offline `fallback` into the enriched `FetchedPrompt`
- * shape (D7), so `fetch()` returns an identical shape on the online and
+ * shape (D7), so `render()` returns an identical shape on the online and
  * offline paths. An already-enriched `FetchedPrompt` is returned as-is; a
  * legacy `ResolvedPrompt` is lifted (messages synthesized; `releaseId` → its
  * own value or explicit `null`; `blockRenderRecord` → `{}`; `variantName`
@@ -261,34 +272,48 @@ function buildLabelEventsQuery(input: ListLabelEventsInput): string {
 }
 
 /**
- * Init-time config for the env-aware `fetch()` surface (TO11-980 / S9).
+ * Init-time config for the env-aware `render()` surface (TO11-980 / S9).
  *
  * `projectId` and `env` come from `createClient`. `projectId` is required for
- * `fetch()` (it builds the project-scoped resolve path); `env` is the default
- * serving environment inherited by every `fetch(slug)` call.
+ * `render()` (it builds the project-scoped resolve path); `env` is the default
+ * serving environment inherited by every `render(slug)` call.
  */
 export interface PromptResourceConfig {
-	/** Project the client is bound to. Required for `fetch()`; validated at createClient. */
+	/** Project the client is bound to. Required for `render()`; validated at createClient. */
 	projectId?: string;
-	/** Default serving env for `fetch()`. Validated against ENV_SLUG_REGEX at createClient. */
+	/** Default serving env for `render()`. Validated against ENV_SLUG_REGEX at createClient. */
 	env?: string;
+	/** Default provider shape for `render()` output. Per-call override allowed. */
+	format?: RenderFormat;
+	/**
+	 * Default unknown-role policy for `render({ format })` output conversion.
+	 * Per-call override allowed; defaults to `"drop"`.
+	 */
+	onUnknownRole?: UnknownRoleMode;
 }
 
-export class PromptResource {
+export class PromptResource<F extends RenderFormat | undefined = undefined> {
 	private readonly transport: Transport;
 	private readonly cache: PromptCache;
 	private readonly projectId: string | undefined;
 	private readonly env: string | undefined;
+	private readonly format: RenderFormat | undefined;
+	private readonly onUnknownRole: UnknownRoleMode | undefined;
 
 	constructor(
 		transport: Transport,
 		cacheConfig?: CacheConfig,
-		config?: PromptResourceConfig,
+		// `format` is bound to the class generic `F` (not the wider `RenderFormat`)
+		// so the constructed default shape cannot disagree with what `render()`'s
+		// return type (`RenderResult<F>`) promises.
+		config?: Omit<PromptResourceConfig, "format"> & { format?: F },
 	) {
 		this.transport = transport;
 		this.cache = new PromptCache(cacheConfig);
 		this.projectId = config?.projectId;
 		this.env = config?.env;
+		this.format = config?.format;
+		this.onUnknownRole = config?.onUnknownRole;
 	}
 
 	// ─── Create ──────────────────────────────────────────────────────────────
@@ -436,35 +461,65 @@ export class PromptResource {
 		return unwrap(envelope);
 	}
 
-	// ─── Fetch (env-aware resolution, TO11-980 / S9) ──────────────────────────
+	// ─── Render (env-aware resolution + format shaping, TO11-980 / TO11-2691) ──
+
+	/**
+	 * Resolve and (optionally) shape a prompt for the client's configured
+	 * `projectId` + `env`, in one control-plane request. With a `format` (per
+	 * call or inherited from the client) the result is provider-shaped
+	 * `{ messages, config, metadata }`; without one it is the neutral
+	 * `FetchedPrompt`. Resolves by the client's `env`; for label-addressed
+	 * resolution see {@link PromptResource.resolve | `resolve()`}.
+	 *
+	 * @example Render an OpenAI-shaped prompt and send it through the gateway
+	 * 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) },
+	 * );
+	 */
+	async render(
+		slug: string,
+		options: RenderOptions & { format: "openai" },
+	): Promise<OpenAiRenderedPrompt>;
+	async render(
+		slug: string,
+		options: RenderOptions & { format: "anthropic" },
+	): Promise<AnthropicRenderedPrompt>;
+	async render(slug: string, options?: RenderOptions): Promise<RenderResult<F>>;
+	async render(
+		slug: string,
+		options: RenderOptions = {},
+	): Promise<FetchedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt> {
+		const fetched = await this.resolveToFetched(slug, options);
+		return shapePrompt(fetched, options.format ?? this.format, {
+			onUnknownRole: options.onUnknownRole ?? this.onUnknownRole,
+		});
+	}
 
 	/**
-	 * Resolve a prompt for the client's configured `projectId` + `env`
-	 * (Style-A). The ergonomic slug-first surface: env is configured once at
-	 * `createClient` and inherited here, with an optional per-call override.
+	 * Env-aware resolution → neutral `FetchedPrompt`. Carries the resolve /
+	 * cache / offline-fallback logic; `render()` is the public shaping surface.
 	 *
-	 * - **env→label wire mapping (correction #3):** the resolve route is
-	 *   label-based (`/v1/projects/:projectId/prompts:resolve`, body
-	 *   `labels[]`); it does NOT accept a top-level `env` field. The resolved
-	 *   env slug (lowercase-kebab — a valid label name) is therefore sent as
-	 *   the single resolution label: body `{ slug, labels: [env], subject?,
-	 *   variables? }`.
+	 * - **env→label wire mapping:** the resolve route is label-based
+	 *   (`/v1/projects/:projectId/prompts:resolve`, body `labels[]`); the
+	 *   resolved env slug is sent as the single resolution label.
 	 * - **No silent fallback (R4):** if no env is resolvable (none at init AND
-	 *   none per call) this throws `EnvNotFoundError` (`reason.source =
-	 *   "missing"`) CLIENT-side, eagerly, before any transport call.
+	 *   none per call) this throws `EnvNotFoundError` CLIENT-side, eagerly,
+	 *   before any transport call.
 	 * - **Cache (D8):** caches `single`-strategy releases and weighted releases
 	 *   WITH a `subject`; BYPASSES the cache for weighted releases with NO
 	 *   `subject` (a uniform-random assignment must not be pinned for the TTL).
-	 *
-	 * Prefer this over the deprecated `resolve()`.
 	 */
-	async fetch(
+	private async resolveToFetched(
 		slug: string,
 		options: FetchPromptOptions = {},
 	): Promise<FetchedPrompt> {
 		if (this.projectId === undefined || this.projectId.trim() === "") {
 			throw new Error(
-				"[to11ai/sdk] `prompts.fetch()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).",
+				"[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).",
 			);
 		}
 
@@ -486,13 +541,7 @@ export class PromptResource {
 			);
 		}
 
-		const {
-			subject,
-			variables,
-			cache: useCache = true,
-			fallback,
-			developerRole,
-		} = options;
+		const { subject, variables, cache: useCache = true, fallback } = options;
 
 		const cacheKey = buildFetchCacheKey(
 			this.projectId,
@@ -500,7 +549,6 @@ export class PromptResource {
 			env,
 			subject,
 			variables,
-			developerRole,
 		);
 
 		if (useCache) {
@@ -514,7 +562,6 @@ export class PromptResource {
 		const body: Record<string, unknown> = { slug, labels: [env] };
 		if (subject !== undefined) body.subject = subject;
 		if (variables !== undefined) body.variables = variables;
-		if (developerRole !== undefined) body.developerRole = developerRole;
 
 		try {
 			const envelope = await this.transport.request<ResolvedPromptEnvelope>(
@@ -561,12 +608,13 @@ export class PromptResource {
 	// ─── Resolve ──────────────────────────────────────────────────────────────
 
 	/**
-	 * @deprecated Use {@link PromptResource.fetch | `prompts.fetch(slug,
-	 * options?)`} instead. `resolve()` is env-agnostic (no `env` / `subject`,
-	 * no enriched release/variant provenance, no typed-env errors)
-	 * and is retained only for back-compat. It is NOT subject to the R4
-	 * no-silent-fallback env gate (it has no env concept). New code should
-	 * configure `projectId` + `env` at `createClient` and call `fetch()`.
+	 * Resolve a prompt by explicit `labels` for a given `projectId`, in one
+	 * control-plane request. This is the label-addressed counterpart to
+	 * {@link PromptResource.render | `render()`}, which resolves by the client's
+	 * configured `env`. Reach for `resolve()` when you address prompts by label
+	 * rather than by environment; it is env-agnostic, so it carries no `env` /
+	 * `subject`, no enriched release/variant provenance, and no typed-env errors,
+	 * and is not subject to the env-based no-silent-fallback gate.
 	 */
 	async resolve(input: ResolvePromptInput): Promise<ResolvePromptResult> {
 		const {

package/src/prompts/shape.ts

@@ -0,0 +1,149 @@
+/**
+ * Format-at-load shaping: turn a neutral `FetchedPrompt` into a provider-shaped
+ * `{ messages, config, metadata }` result the caller spreads into their own
+ * provider `create()` call. Header-only — this only reshapes data, it never
+ * sends a request. See docs/product-specs/2026-07-14-to11-2691-sdk-simpler-setup.md.
+ */
+
+import {
+	type AnthropicMessage,
+	type AnthropicTool,
+	type AnthropicToolChoice,
+	type ConvertMessagesOptions,
+	type OpenAIChatMessage,
+	type OpenAITool,
+	type OpenAIToolChoice,
+	toAnthropicMessages,
+	toAnthropicSystem,
+	toAnthropicToolChoice,
+	toAnthropicTools,
+	toOpenAIMessages,
+	toOpenAIToolChoice,
+	toOpenAITools,
+} from "../gateway";
+import type { FetchedPrompt, RenderFormat } from "./types";
+
+/** Model params passed through verbatim from the resolved version's modelConfig. */
+export interface PromptConfig {
+	model?: string;
+	temperature?: number;
+	// Snake_case to match the stored modelConfig and the provider wire key
+	// (spread verbatim into e.g. OpenAI's `create()`), per TO11-2691.
+	max_tokens?: number;
+	/** Any additional stored model-config keys are passed through unchanged. */
+	[key: string]: unknown;
+}
+
+/** Prompt provenance for `turn.headers()` — kept apart from the request body. */
+export interface PromptMetadata {
+	promptId: string;
+	versionId: string;
+	version: number;
+	releaseId: string | null;
+	/** The single label the prompt resolved through (env slug today). */
+	label: string;
+	variantName?: string;
+}
+
+/** OpenAI-shaped render result: spread `{ ...config, messages }` into create(). */
+export interface OpenAiRenderedPrompt {
+	messages: OpenAIChatMessage[];
+	config: PromptConfig;
+	metadata: PromptMetadata;
+	/** Authored tools, provider-shaped. Present only when the prompt declares tools. */
+	tools?: OpenAITool[];
+	/** Authored tool-choice directive. Present only when the prompt sets one. */
+	tool_choice?: OpenAIToolChoice;
+}
+
+/** Anthropic-shaped render result: system/developer folded into `system`. */
+export interface AnthropicRenderedPrompt {
+	/** Folded system/developer instruction text (Anthropic's top-level `system`). */
+	system?: string;
+	messages: AnthropicMessage[];
+	config: PromptConfig;
+	metadata: PromptMetadata;
+	/** Authored tools, provider-shaped. Present only when the prompt declares tools. */
+	tools?: AnthropicTool[];
+	/** Authored tool-choice directive. Present only when the prompt sets one. */
+	tool_choice?: AnthropicToolChoice;
+}
+
+/** The render return type for a given client/call format. */
+export type RenderResult<F extends RenderFormat | undefined> =
+	F extends "openai"
+		? OpenAiRenderedPrompt
+		: F extends "anthropic"
+			? AnthropicRenderedPrompt
+			: FetchedPrompt;
+
+function toPromptConfig(modelConfig: unknown): PromptConfig {
+	return modelConfig !== null && typeof modelConfig === "object"
+		? { ...(modelConfig as Record<string, unknown>) }
+		: {};
+}
+
+function toMetadata(prompt: FetchedPrompt): PromptMetadata {
+	const metadata: PromptMetadata = {
+		promptId: prompt.promptId,
+		versionId: prompt.versionId,
+		version: prompt.version,
+		releaseId: prompt.releaseId,
+		label: prompt.label,
+	};
+	if (prompt.variantName !== undefined)
+		metadata.variantName = prompt.variantName;
+	return metadata;
+}
+
+export function shapeOpenAI(
+	prompt: FetchedPrompt,
+	options: ConvertMessagesOptions = {},
+): OpenAiRenderedPrompt {
+	const result: OpenAiRenderedPrompt = {
+		messages: toOpenAIMessages(prompt.messages, options),
+		config: toPromptConfig(prompt.modelConfig),
+		metadata: toMetadata(prompt),
+	};
+	// Carry authored tools so the spread-ready result is complete for
+	// tool-using prompts. Omit when empty/absent so we never send `tools: []`.
+	const tools = toOpenAITools(prompt.tools);
+	if (tools.length > 0) result.tools = tools;
+	const toolChoice = toOpenAIToolChoice(prompt.toolChoice);
+	if (toolChoice !== undefined) result.tool_choice = toolChoice;
+	return result;
+}
+
+export function shapeAnthropic(
+	prompt: FetchedPrompt,
+	options: ConvertMessagesOptions = {},
+): AnthropicRenderedPrompt {
+	const result: AnthropicRenderedPrompt = {
+		messages: toAnthropicMessages(prompt.messages, options),
+		config: toPromptConfig(prompt.modelConfig),
+		metadata: toMetadata(prompt),
+	};
+	const system = toAnthropicSystem(prompt.messages);
+	if (system !== undefined) result.system = system;
+	const tools = toAnthropicTools(prompt.tools);
+	if (tools.length > 0) result.tools = tools;
+	const toolChoice = toAnthropicToolChoice(prompt.toolChoice);
+	if (toolChoice !== undefined) result.tool_choice = toolChoice;
+	return result;
+}
+
+/** Shape a fetched prompt for `format`, or return it neutral when unset. */
+export function shapePrompt(
+	prompt: FetchedPrompt,
+	format: RenderFormat | undefined,
+	options: ConvertMessagesOptions = {},
+): FetchedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt {
+	switch (format) {
+		case "openai":
+			return shapeOpenAI(prompt, options);
+		case "anthropic":
+			return shapeAnthropic(prompt, options);
+		default:
+			return prompt;
+	}
+}

package/src/prompts/types.ts

@@ -38,6 +38,18 @@ export type RenderedChatMessage = GenRenderedChatPrompt["messages"][number];
 
 export type RenderedPrompt = GenRenderedPrompt;
 
+/** Provider shape for `prompts.render()` output. Omit for the neutral result. */
+export type RenderFormat = "openai" | "anthropic";
+
+/**
+ * Policy for a message whose role is outside the known set
+ * (`system | user | assistant | developer | tool`) when converting to a
+ * provider shape. `"drop"` (default) omits it silently; `"warn"` omits it and
+ * emits a `console.warn`; `"error"` throws `UnknownRoleError`. Applies to the
+ * standalone converters and to `render({ format })`.
+ */
+export type UnknownRoleMode = "drop" | "warn" | "error";
+
 /**
  * A provider-neutral tool definition (`{ name, description?, parameters }`),
  * sourced from authored tool-definition blocks. Surfaced on the resolved
@@ -56,11 +68,12 @@ export type ResolvedPrompt = Pick<
 	| "promptId"
 	| "versionId"
 	| "version"
-	| "labels"
+	| "label"
 	| "contentHash"
 	| "rendered"
 	| "tools"
 	| "toolChoice"
+	| "modelConfig"
 >;
 
 export interface PaginationInfo {
@@ -190,8 +203,19 @@ export interface FetchedPrompt {
 	promptId: string;
 	versionId: string;
 	contentHash: string;
-	labels: string[];
+	/**
+	 * The single label the prompt resolved through — the env slug today, a real
+	 * label once labels ship. Surfaced as `x-to11-prompt-label` by
+	 * `gatewayPromptHeaders` / `turn.headers()` (TO11-2725).
+	 */
+	label: string;
 	rendered: RenderedPrompt;
+	/**
+	 * The served version's model config (model, temperature, max_tokens, …),
+	 * passed through verbatim. Surfaced as `config` by `render({ format })`.
+	 * Optional: absent when a pre-`modelConfig` API omits it.
+	 */
+	modelConfig?: unknown;
 	/**
 	 * Provider-neutral tool definitions lifted from authored tool-definition
 	 * blocks. Absent (rather than `[]`) when the resolved version declares no
@@ -215,26 +239,23 @@ export type ResolvedPromptEnvelope = GenResolvedPrompt & {
 	strategy?: "single" | "weighted";
 };
 
-/**
- * How an authored `developer` block is rendered. The caller controls this
- * per-call because it knows the upstream it targets. Omitted ⇒ `"user"`
- * (back-compatible; safe for any upstream). `"developer"` preserves the role
- * (OpenAI); `"system"` folds it into a system message.
- */
-export type DeveloperRole = "user" | "developer" | "system";
-
 export interface FetchPromptOptions {
 	env?: string;
 	subject?: string;
 	variables?: Record<string, unknown>;
 	cache?: boolean;
 	fallback?: ResolvedPrompt | FetchedPrompt;
+}
+
+export interface RenderOptions extends FetchPromptOptions {
+	/** Provider shape for this call's output; overrides the client default. */
+	format?: RenderFormat;
 	/**
-	 * How authored `developer` blocks render. Default `"user"`. Forwarded on the
-	 * resolve request and folded into the cache key so two calls differing only
-	 * by `developerRole` never share a cached result.
+	 * How to handle a message with an unrecognized role while shaping for a
+	 * provider (`format` set). Overrides the client default; defaults to `"drop"`.
+	 * Only meaningful with a `format` — the neutral result runs no converter.
 	 */
-	developerRole?: DeveloperRole;
+	onUnknownRole?: UnknownRoleMode;
 }
 
 export type PaletteToken = ProjectPromptLabel["displayColor"];