@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/src/prompts/shape.ts

@@ -0,0 +1,152 @@
+/**
+ * Format-at-load shaping: turn a neutral `RenderedPrompt` 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 { RenderedPrompt, 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;
+	/** The prompt's human-readable slug — surfaced as `x-to11-prompt-slug`. */
+	slug: 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
+			: RenderedPrompt;
+
+function toPromptConfig(modelConfig: unknown): PromptConfig {
+	return modelConfig !== null && typeof modelConfig === "object"
+		? { ...(modelConfig as Record<string, unknown>) }
+		: {};
+}
+
+function toMetadata(prompt: RenderedPrompt): PromptMetadata {
+	const metadata: PromptMetadata = {
+		promptId: prompt.promptId,
+		versionId: prompt.versionId,
+		version: prompt.version,
+		releaseId: prompt.releaseId,
+		label: prompt.label,
+		slug: prompt.slug,
+	};
+	if (prompt.variantName !== undefined)
+		metadata.variantName = prompt.variantName;
+	return metadata;
+}
+
+export function shapeOpenAI(
+	prompt: RenderedPrompt,
+	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: RenderedPrompt,
+	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 rendered prompt for `format`, or return it neutral when unset. */
+export function shapePrompt(
+	prompt: RenderedPrompt,
+	format: RenderFormat | undefined,
+	options: ConvertMessagesOptions = {},
+): RenderedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt {
+	switch (format) {
+		case "openai":
+			return shapeOpenAI(prompt, options);
+		case "anthropic":
+			return shapeAnthropic(prompt, options);
+		default:
+			return prompt;
+	}
+}

package/src/prompts/types.ts

@@ -6,7 +6,6 @@ import type {
 	PromptLabelPointer as GenPromptLabelPointer,
 	PromptVersion as GenPromptVersion,
 	RenderedChatPrompt as GenRenderedChatPrompt,
-	RenderedPrompt as GenRenderedPrompt,
 	ResolvedPrompt as GenResolvedPrompt,
 	ResolvedToolCall as GenResolvedToolCall,
 	ResolvedToolDefinition as GenResolvedToolDefinition,
@@ -24,19 +23,27 @@ export type PromptVersion = GenPromptVersion;
 export type PromptFormat = PromptVersion["format"];
 export type PromptLabelPointer = GenPromptLabelPointer;
 
-export type TextChatRole = "system" | "user" | "assistant" | "developer";
+export type ChatRole = "system" | "user" | "assistant" | "developer";
 
-export interface TextChatMessage {
-	role: TextChatRole;
+export interface ChatMessage {
+	role: ChatRole;
 	content: string;
 	disabled?: boolean;
 }
 
-export type ChatMessage = TextChatMessage;
-
 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 }`),
@@ -56,11 +63,12 @@ export type ResolvedPrompt = Pick<
 	| "promptId"
 	| "versionId"
 	| "version"
-	| "labels"
+	| "label"
 	| "contentHash"
 	| "rendered"
 	| "tools"
 	| "toolChoice"
+	| "modelConfig"
 >;
 
 export interface PaginationInfo {
@@ -76,7 +84,7 @@ export interface PaginatedResult<T> {
 }
 
 export interface CreatePromptInput {
-	projectId: string;
+	projectId?: string;
 	name: string;
 	slug: string;
 	description?: string;
@@ -86,7 +94,7 @@ export interface CreatePromptInput {
 export type CreatePromptResult = Prompt;
 
 export interface ListPromptsInput {
-	projectId: string;
+	projectId?: string;
 	status?: PromptStatus;
 	sortBy?: "createdAt" | "updatedAt" | "name";
 	tags?: string;
@@ -97,14 +105,14 @@ export interface ListPromptsInput {
 export type ListPromptsResult = Prompt;
 
 export interface GetPromptInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 }
 
 export type GetPromptResult = Prompt;
 
 export interface UpdatePromptInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 	name?: string;
 	description?: string | null;
@@ -114,14 +122,14 @@ export interface UpdatePromptInput {
 export type UpdatePromptResult = Prompt;
 
 export interface ArchivePromptInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 }
 
 export type ArchivePromptResult = Prompt;
 
 export interface CreatePromptVersionInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 	format: PromptFormat;
 	templateJson: unknown;
@@ -133,14 +141,14 @@ export interface CreatePromptVersionInput {
 export type CreatePromptVersionResult = PromptVersion;
 
 export interface ListPromptVersionsInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 }
 
 export type ListPromptVersionsResult = PromptVersion[];
 
 export interface GetPromptVersionInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 	versionNumber: number;
 }
@@ -148,7 +156,7 @@ export interface GetPromptVersionInput {
 export type GetPromptVersionResult = PromptVersion;
 
 export interface MovePromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 	label: string;
 	versionId: string;
@@ -158,30 +166,24 @@ export interface MovePromptLabelInput {
 export type MovePromptLabelResult = PromptLabelPointer;
 
 export interface ListPromptLabelsInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 }
 
 export type ListPromptLabelsResult = PromptLabelPointer[];
 
-export interface ResolvePromptInput {
-	projectId: string;
-	slug: string;
-	labels: string[];
-	variables?: Record<string, unknown>;
-	/** Set false to bypass the LRU cache for this call. Default: true */
-	cache?: boolean;
-	/** Fallback prompt served if the API is unreachable and cache is empty. */
-	fallback?: ResolvedPrompt;
-}
-
-export type ResolvePromptResult = ResolvedPrompt;
-
+/**
+ * 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 const ENV_SLUG_REGEX = /^[a-z0-9-]{1,63}$/;
 
 export type BlockRenderRecord = Record<string, "rendered" | "dimmed">;
 
-export interface FetchedPrompt {
+export interface RenderedPrompt {
 	messages: RenderedChatMessage[];
 	version: number;
 	releaseId: string | null;
@@ -190,8 +192,24 @@ export interface FetchedPrompt {
 	promptId: string;
 	versionId: string;
 	contentHash: string;
-	labels: string[];
-	rendered: RenderedPrompt;
+	/**
+	 * 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;
+	/**
+	 * The prompt's human-readable slug (the `render()` input). Surfaced as
+	 * `x-to11-prompt-slug` by `gatewayPromptHeaders` / `turn.headers()` so traces
+	 * carry a readable name alongside the opaque `promptId` (TO11-2727).
+	 */
+	slug: string;
+	/**
+	 * 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
@@ -204,37 +222,31 @@ export interface FetchedPrompt {
 	 * into `toOpenAIToolChoice` / `toAnthropicToolChoice`.
 	 *
 	 * `NonNullable` because `normalizeResolvedEnvelope` maps wire-`null` to absent,
-	 * so a present `FetchedPrompt.toolChoice` is never `null` — callers get the
+	 * so a present `RenderedPrompt.toolChoice` is never `null` — callers get the
 	 * key or nothing, and never have to branch on `null`.
 	 */
 	toolChoice?: NonNullable<ResolvedPrompt["toolChoice"]>;
 }
 
-export type ResolvedPromptEnvelope = GenResolvedPrompt & {
-	/** Active release strategy. Used to decide weighted-no-subject cache bypass (D8). */
-	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 type ResolvedPromptEnvelope = GenResolvedPrompt;
 
-export interface FetchPromptOptions {
-	env?: string;
-	subject?: string;
+export interface RenderOptions {
+	/**
+	 * 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;
 	variables?: Record<string, unknown>;
-	cache?: boolean;
-	fallback?: ResolvedPrompt | FetchedPrompt;
+	/** 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;
 	/**
-	 * 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"];
@@ -246,7 +258,7 @@ export type ProjectPromptLabelUsage = GenProjectPromptLabelUsage;
 export type PromptLabelEvent = GenPromptLabelEvent;
 
 export interface ListProjectPromptLabelsInput {
-	projectId: string;
+	projectId?: string;
 	/** Set true to include archived (soft-deleted) entries. Default: false. */
 	includeArchived?: boolean;
 }
@@ -254,7 +266,7 @@ export interface ListProjectPromptLabelsInput {
 export type ListProjectPromptLabelsResult = ProjectPromptLabel[];
 
 export interface CreateProjectPromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	label: string;
 	isDefault?: boolean;
 	description?: string;
@@ -264,14 +276,14 @@ export interface CreateProjectPromptLabelInput {
 export type CreateProjectPromptLabelResult = ProjectPromptLabel;
 
 export interface GetProjectPromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	label: string;
 }
 
 export type GetProjectPromptLabelResult = ProjectPromptLabel;
 
 export interface UpdateProjectPromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	label: string;
 	isDefault?: boolean;
 	description?: string | null;
@@ -281,14 +293,14 @@ export interface UpdateProjectPromptLabelInput {
 export type UpdateProjectPromptLabelResult = ProjectPromptLabel;
 
 export interface DeleteProjectPromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	label: string;
 }
 
 export type DeleteProjectPromptLabelResult = ProjectPromptLabel;
 
 export interface ListProjectPromptLabelUsagesInput {
-	projectId: string;
+	projectId?: string;
 	label: string;
 }
 
@@ -297,7 +309,7 @@ export type ListProjectPromptLabelUsagesResult = ProjectPromptLabelUsage[];
 export type ListLabelEventsInput =
 	| {
 			scope: "label";
-			projectId: string;
+			projectId?: string;
 			promptId: string;
 			label: string;
 			page?: number;
@@ -307,7 +319,7 @@ export type ListLabelEventsInput =
 	  }
 	| {
 			scope: "prompt";
-			projectId: string;
+			projectId?: string;
 			promptId: string;
 			label?: string;
 			page?: number;
@@ -317,7 +329,7 @@ export type ListLabelEventsInput =
 	  }
 	| {
 			scope: "project";
-			projectId: string;
+			projectId?: string;
 			promptId?: string;
 			label?: string;
 			page?: number;

package/src/transport.ts

@@ -1,8 +1,7 @@
 import type { BehaviorStore } from "./behaviors/store";
 import {
-	AmbiguousEnvLabelsError,
 	EnvNotEnabledForProviderError,
-	EnvNotFoundError,
+	LabelNotFoundError,
 	NoActiveReleaseError,
 	NoApplicableRouteError,
 	PromptLabelNotRegisteredError,
@@ -108,14 +107,11 @@ function mapPromptResolveError(
 		);
 	}
 	if (detailsCode === "ENV_NOT_FOUND") {
-		// Server-side unknown-env. (The client-eager "missing" variant is
-		// raised in resource.ts before any request — never here.)
-		return new EnvNotFoundError(
-			message,
-			{ env, source: "unknown" },
-			details,
-			status,
-		);
+		// Server-side unknown-label. (The client-side MissingLabelError — no
+		// label supplied at all — is raised in resource.ts before any request.)
+		// Prefer `details.label`, falling back to `details.env`.
+		const label = typeof d.label === "string" ? d.label : env;
+		return new LabelNotFoundError(message, label, details, status);
 	}
 	if (detailsCode === "NO_ACTIVE_RELEASE") {
 		return new NoActiveReleaseError(
@@ -125,9 +121,6 @@ function mapPromptResolveError(
 			status,
 		);
 	}
-	if (detailsCode === "AMBIGUOUS_ENV_LABELS") {
-		return new AmbiguousEnvLabelsError(message, { env, slug }, details, status);
-	}
 	if (PROMPT_POLICY_VIOLATION_DETAILS_CODES.has(detailsCode)) {
 		const policy = typeof d.policy === "string" ? d.policy : undefined;
 		return new PromptPolicyViolationError(
@@ -140,9 +133,9 @@ function mapPromptResolveError(
 	return undefined;
 }
 
-export type AuthConfig =
-	| { readonly apiKey: string; readonly getAccessToken?: never }
-	| { readonly getAccessToken: () => Promise<string>; readonly apiKey?: never };
+export interface AuthConfig {
+	readonly apiKey: string;
+}
 
 export interface TransportConfig {
 	readonly baseUrl: string;
@@ -248,12 +241,25 @@ function mapHttpError(
 	}
 	if (status === 429) {
 		const retryAfterHeader = headers?.get("retry-after");
-		const retryAfterSeconds = retryAfterHeader
-			? Number(retryAfterHeader)
-			: undefined;
+		let retryAfterSeconds: number | undefined;
+		if (retryAfterHeader) {
+			const numeric = Number(retryAfterHeader);
+			if (Number.isFinite(numeric)) {
+				retryAfterSeconds = Math.max(0, numeric);
+			} else {
+				// RFC 9110 HTTP-date form → seconds until that instant.
+				const when = Date.parse(retryAfterHeader);
+				if (!Number.isNaN(when)) {
+					retryAfterSeconds = Math.max(
+						0,
+						Math.round((when - Date.now()) / 1000),
+					);
+				}
+			}
+		}
 		return new To11aiRateLimitError(
 			message,
-			Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
+			retryAfterSeconds,
 			errorCode,
 			details,
 		);
@@ -395,25 +401,20 @@ export class Transport {
 	private readonly behaviorStore: BehaviorStore | undefined;
 
 	constructor(config: TransportConfig) {
-		this.baseUrl = config.baseUrl.replace(/\/$/, "");
+		this.baseUrl = config.baseUrl.replace(/\/+$/, "");
 		this.auth = config.auth;
 		this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 		this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
 		this.behaviorStore = config.behaviorStore;
 	}
 
-	private async buildHeaders(): Promise<Record<string, string>> {
+	private buildHeaders(): Record<string, string> {
 		const headers: Record<string, string> = {
 			"content-type": "application/json",
 			accept: "application/json",
 		};
 
-		if (this.auth.apiKey !== undefined) {
-			headers.authorization = `Bearer ${this.auth.apiKey}`;
-		} else if (this.auth.getAccessToken) {
-			const token = await this.auth.getAccessToken();
-			headers.authorization = `Bearer ${token}`;
-		}
+		headers.authorization = `Bearer ${this.auth.apiKey}`;
 
 		const tp = activeTraceContext();
 		if (tp) {
@@ -452,7 +453,7 @@ export class Transport {
 		let attempt = 0;
 
 		while (true) {
-			const headers = await this.buildHeaders();
+			const headers = this.buildHeaders();
 			const controller = new AbortController();
 			const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
 
@@ -495,16 +496,28 @@ export class Transport {
 				let json: ApiEnvelope<T> | undefined;
 				const text = await response.text();
 
-				try {
-					json = JSON.parse(text) as ApiEnvelope<T>;
-				} catch {
-					// Not a JSON body — treat as generic API error
-					throw mapHttpError(
-						response.status,
-						null,
-						text || response.statusText,
-						response.headers,
-					);
+				if (text === "" && response.ok) {
+					// A successful empty body (e.g. 204): synthesize an empty-data
+					// envelope rather than mis-mapping it to an API error.
+					json = {
+						success: true,
+						code: response.status,
+						data: null,
+						error: null,
+						pagination: null,
+					} as ApiEnvelope<T>;
+				} else {
+					try {
+						json = JSON.parse(text) as ApiEnvelope<T>;
+					} catch {
+						// Not a JSON body — treat as generic API error
+						throw mapHttpError(
+							response.status,
+							null,
+							text || response.statusText,
+							response.headers,
+						);
+					}
 				}
 
 				if (!response.ok) {
@@ -554,7 +567,7 @@ export class Transport {
 				const isTimeout =
 					err instanceof DOMException && err.name === "AbortError";
 				// Only retry on genuine network failures (fetch throws TypeError) or timeouts.
-				// Unexpected errors (e.g. getAccessToken rejections) propagate immediately.
+				// Other unexpected errors propagate immediately.
 				const isNetworkError = err instanceof TypeError;
 
 				if (