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

package/src/prompts/shape.ts

@@ -1,5 +1,5 @@
 /**
- * Format-at-load shaping: turn a neutral `FetchedPrompt` into a provider-shaped
+ * 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.
@@ -21,7 +21,7 @@ import {
 	toOpenAIToolChoice,
 	toOpenAITools,
 } from "../gateway";
-import type { FetchedPrompt, RenderFormat } from "./types";
+import type { RenderedPrompt, RenderFormat } from "./types";
 
 /** Model params passed through verbatim from the resolved version's modelConfig. */
 export interface PromptConfig {
@@ -42,6 +42,8 @@ export interface PromptMetadata {
 	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;
 }
 
@@ -75,7 +77,7 @@ export type RenderResult<F extends RenderFormat | undefined> =
 		? OpenAiRenderedPrompt
 		: F extends "anthropic"
 			? AnthropicRenderedPrompt
-			: FetchedPrompt;
+			: RenderedPrompt;
 
 function toPromptConfig(modelConfig: unknown): PromptConfig {
 	return modelConfig !== null && typeof modelConfig === "object"
@@ -83,13 +85,14 @@ function toPromptConfig(modelConfig: unknown): PromptConfig {
 		: {};
 }
 
-function toMetadata(prompt: FetchedPrompt): PromptMetadata {
+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;
@@ -97,7 +100,7 @@ function toMetadata(prompt: FetchedPrompt): PromptMetadata {
 }
 
 export function shapeOpenAI(
-	prompt: FetchedPrompt,
+	prompt: RenderedPrompt,
 	options: ConvertMessagesOptions = {},
 ): OpenAiRenderedPrompt {
 	const result: OpenAiRenderedPrompt = {
@@ -115,7 +118,7 @@ export function shapeOpenAI(
 }
 
 export function shapeAnthropic(
-	prompt: FetchedPrompt,
+	prompt: RenderedPrompt,
 	options: ConvertMessagesOptions = {},
 ): AnthropicRenderedPrompt {
 	const result: AnthropicRenderedPrompt = {
@@ -134,10 +137,10 @@ export function shapeAnthropic(
 
 /** Shape a fetched prompt for `format`, or return it neutral when unset. */
 export function shapePrompt(
-	prompt: FetchedPrompt,
+	prompt: RenderedPrompt,
 	format: RenderFormat | undefined,
 	options: ConvertMessagesOptions = {},
-): FetchedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt {
+): RenderedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt {
 	switch (format) {
 		case "openai":
 			return shapeOpenAI(prompt, options);

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,
@@ -36,8 +35,6 @@ 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";
 
@@ -89,7 +86,7 @@ export interface PaginatedResult<T> {
 }
 
 export interface CreatePromptInput {
-	projectId: string;
+	projectId?: string;
 	name: string;
 	slug: string;
 	description?: string;
@@ -99,7 +96,7 @@ export interface CreatePromptInput {
 export type CreatePromptResult = Prompt;
 
 export interface ListPromptsInput {
-	projectId: string;
+	projectId?: string;
 	status?: PromptStatus;
 	sortBy?: "createdAt" | "updatedAt" | "name";
 	tags?: string;
@@ -110,14 +107,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;
@@ -127,14 +124,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;
@@ -146,14 +143,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;
 }
@@ -161,7 +158,7 @@ export interface GetPromptVersionInput {
 export type GetPromptVersionResult = PromptVersion;
 
 export interface MovePromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	promptId: string;
 	label: string;
 	versionId: string;
@@ -171,30 +168,17 @@ 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;
-
 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;
@@ -209,7 +193,12 @@ export interface FetchedPrompt {
 	 * `gatewayPromptHeaders` / `turn.headers()` (TO11-2725).
 	 */
 	label: string;
-	rendered: RenderedPrompt;
+	/**
+	 * 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 })`.
@@ -228,7 +217,7 @@ 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"]>;
@@ -239,15 +228,16 @@ export type ResolvedPromptEnvelope = GenResolvedPrompt & {
 	strategy?: "single" | "weighted";
 };
 
-export interface FetchPromptOptions {
+export interface RenderOptions {
+	/** Serving environment for this call; overrides the client default. */
 	env?: 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;
-	fallback?: ResolvedPrompt | FetchedPrompt;
-}
-
-export interface RenderOptions extends FetchPromptOptions {
+	/** Prompt served if the API is unreachable on a network error and cache is empty. */
+	fallback?: RenderedPrompt;
 	/** Provider shape for this call's output; overrides the client default. */
 	format?: RenderFormat;
 	/**
@@ -267,7 +257,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;
 }
@@ -275,7 +265,7 @@ export interface ListProjectPromptLabelsInput {
 export type ListProjectPromptLabelsResult = ProjectPromptLabel[];
 
 export interface CreateProjectPromptLabelInput {
-	projectId: string;
+	projectId?: string;
 	label: string;
 	isDefault?: boolean;
 	description?: string;
@@ -285,14 +275,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;
@@ -302,14 +292,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;
 }
 
@@ -318,7 +308,7 @@ export type ListProjectPromptLabelUsagesResult = ProjectPromptLabelUsage[];
 export type ListLabelEventsInput =
 	| {
 			scope: "label";
-			projectId: string;
+			projectId?: string;
 			promptId: string;
 			label: string;
 			page?: number;
@@ -328,7 +318,7 @@ export type ListLabelEventsInput =
 	  }
 	| {
 			scope: "prompt";
-			projectId: string;
+			projectId?: string;
 			promptId: string;
 			label?: string;
 			page?: number;
@@ -338,7 +328,7 @@ export type ListLabelEventsInput =
 	  }
 	| {
 			scope: "project";
-			projectId: string;
+			projectId?: string;
 			promptId?: string;
 			label?: string;
 			page?: number;