@to11ai/sdk 1.1.0 → 2.0.0-rc.2

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,7 +35,17 @@ 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 +65,12 @@ export type ResolvedPrompt = Pick<
 	| "promptId"
 	| "versionId"
 	| "version"
-	| "labels"
+	| "label"
 	| "contentHash"
 	| "rendered"
 	| "tools"
 	| "toolChoice"
+	| "modelConfig"
 >;
 
 export interface PaginationInfo {
@@ -164,24 +174,11 @@ export interface ListPromptLabelsInput {
 
 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;
@@ -190,8 +187,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,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"]>;
@@ -215,26 +228,24 @@ 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 {
+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;
+	/** 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;
 	/**
-	 * 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"];