@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/dist/prompts/resource.js

@@ -1,20 +1,13 @@
 // src/prompts/resource.ts
-import { z } from "zod";
-import { EnvNotFoundError, To11aiNetworkError } from "../errors";
+import {
+  MissingLabelError,
+  To11aiApiError,
+  To11aiNetworkError
+} from "../errors";
 import { zResolvedPrompt } from "../generated/zod.gen";
-import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
+import { shapePrompt } from "./shape";
 import { ENV_SLUG_REGEX } from "./types";
-var zResolvedPromptLegacy = zResolvedPrompt.pick({
-  promptId: true,
-  versionId: true,
-  version: true,
-  labels: true,
-  contentHash: true,
-  rendered: true,
-  tools: true,
-  toolChoice: true
-});
-var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: z.enum(["single", "weighted"]).optional() });
+var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true });
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
     throw new Error("API returned success but data is null");
@@ -25,12 +18,12 @@ function getProjectPromptsPath(projectId) {
   return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
 }
 function renderedToMessages(rendered) {
-  if (rendered.format === "chat") {
-    return rendered.messages;
+  if (rendered.format !== "chat") {
+    throw new Error("[to11ai/sdk] Unsupported non-chat prompt format; author the prompt as chat blocks.");
   }
-  return [{ role: "user", content: rendered.text }];
+  return rendered.messages;
 }
-function normalizeResolvedEnvelope(raw) {
+function normalizeResolvedEnvelope(raw, slug) {
   const provenance = raw;
   const result = {
     messages: renderedToMessages(raw.rendered),
@@ -40,8 +33,9 @@ function normalizeResolvedEnvelope(raw) {
     promptId: raw.promptId,
     versionId: raw.versionId,
     contentHash: raw.contentHash,
-    labels: raw.labels,
-    rendered: raw.rendered
+    label: raw.label,
+    slug,
+    modelConfig: provenance.modelConfig
   };
   if (raw.tools != null && raw.tools.length > 0) {
     result.tools = raw.tools;
@@ -54,11 +48,11 @@ function normalizeResolvedEnvelope(raw) {
   }
   return result;
 }
-function liftFallbackToFetched(fallback) {
-  if ("messages" in fallback) {
-    return structuredClone(fallback);
+function liftFallbackToRendered(fallback, slug) {
+  if (!Array.isArray(fallback.messages)) {
+    throw new Error("[to11ai/sdk] `fallback` must be a RenderedPrompt (as returned by render()); the legacy resolve() shape is no longer supported.");
   }
-  return normalizeResolvedEnvelope(fallback);
+  return { ...structuredClone(fallback), slug: fallback.slug || slug };
 }
 function getProjectPromptPath(projectId, promptId) {
   return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
@@ -93,22 +87,33 @@ function buildLabelEventsQuery(input) {
 
 class PromptResource {
   transport;
-  cache;
   projectId;
   env;
-  constructor(transport, cacheConfig, config) {
+  format;
+  onUnknownRole;
+  constructor(transport, config) {
     this.transport = transport;
-    this.cache = new PromptCache(cacheConfig);
     this.projectId = config?.projectId;
     this.env = config?.env;
+    this.format = config?.format;
+    this.onUnknownRole = config?.onUnknownRole;
+  }
+  resolveProjectId(perCall) {
+    const projectId = perCall ?? this.projectId;
+    if (projectId === undefined || projectId.trim() === "") {
+      throw new Error("[to11ai/sdk] this call needs a `projectId` — pass it on the call or bind one via createClient({ projectId, ... }).");
+    }
+    return projectId.trim();
   }
   async create(input) {
-    const { projectId, ...body } = input;
+    const { projectId: perCallProjectId, ...body } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("POST", getProjectPromptsPath(projectId), { body });
     return unwrap(envelope);
   }
-  async list(input) {
-    const { projectId, ...queryRest } = input;
+  async list(input = {}) {
+    const { projectId: perCallProjectId, ...queryRest } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("GET", getProjectPromptsPath(projectId), {
       query: {
         ...queryRest
@@ -125,146 +130,111 @@ class PromptResource {
     return { items, pagination };
   }
   async get(input) {
-    const { projectId, promptId } = input;
+    const { projectId: perCallProjectId, promptId } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("GET", getProjectPromptPath(projectId, promptId));
     return unwrap(envelope);
   }
   async update(input) {
-    const { projectId, promptId, ...body } = input;
+    const { projectId: perCallProjectId, promptId, ...body } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("PATCH", getProjectPromptPath(projectId, promptId), { body });
     return unwrap(envelope);
   }
   async archive(input) {
-    const { projectId, promptId } = input;
+    const { projectId: perCallProjectId, promptId } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("DELETE", getProjectPromptPath(projectId, promptId));
     return unwrap(envelope);
   }
   async createVersion(input) {
-    const { projectId, promptId, ...body } = input;
+    const { projectId: perCallProjectId, promptId, ...body } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("POST", `${getProjectPromptPath(projectId, promptId)}/versions`, { body });
     return unwrap(envelope);
   }
   async listVersions(input) {
-    const { projectId, promptId } = input;
+    const { projectId: perCallProjectId, promptId } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/versions`);
     return unwrap(envelope);
   }
   async getVersion(input) {
-    const { projectId, promptId, versionNumber } = input;
+    const { projectId: perCallProjectId, promptId, versionNumber } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/versions/${encodeURIComponent(String(versionNumber))}`);
     return unwrap(envelope);
   }
   async moveLabel(input) {
-    const { projectId, promptId, label, ...body } = input;
+    const { projectId: perCallProjectId, promptId, label, ...body } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("PUT", `${getProjectPromptPath(projectId, promptId)}/labels/${encodeURIComponent(label)}`, { body });
     return unwrap(envelope);
   }
   async listLabels(input) {
-    const { projectId, promptId } = input;
+    const { projectId: perCallProjectId, promptId } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
     return unwrap(envelope);
   }
-  async fetch(slug, options = {}) {
+  async render(slug, options = {}) {
+    const rendered = await this.resolveToRendered(slug, options);
+    return shapePrompt(rendered, options.format ?? this.format, {
+      onUnknownRole: options.onUnknownRole ?? this.onUnknownRole
+    });
+  }
+  async resolveToRendered(slug, options = {}) {
     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, ... }).");
+      throw new Error("[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).");
     }
-    const env = options.env ?? this.env;
-    if (env === undefined) {
-      throw EnvNotFoundError.missing();
+    const label = options.label ?? this.env;
+    if (label === undefined) {
+      throw new MissingLabelError;
     }
-    if (!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 (!ENV_SLUG_REGEX.test(label)) {
+      throw new Error(`[to11ai/sdk] \`label\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(label)}`);
     }
-    const {
-      subject,
-      variables,
-      cache: useCache = true,
-      fallback,
-      developerRole
-    } = options;
-    const cacheKey = buildFetchCacheKey(this.projectId, slug, env, subject, variables, developerRole);
-    if (useCache) {
-      const cached = this.cache.get(cacheKey);
-      if (cached && "messages" in cached)
-        return structuredClone(cached);
-    }
-    const body = { slug, labels: [env] };
-    if (subject !== undefined)
-      body.subject = subject;
+    const { variables, fallback } = options;
+    const body = {};
     if (variables !== undefined)
       body.variables = variables;
-    if (developerRole !== undefined)
-      body.developerRole = developerRole;
     try {
-      const envelope = await this.transport.request("POST", `${getProjectPromptsPath(this.projectId)}:resolve`, {
+      const envelope = await this.transport.request("POST", `${getProjectPromptsPath(this.projectId)}/by-slug/${encodeURIComponent(slug)}/labels/${encodeURIComponent(label)}/render`, {
         body,
         decode: (data) => zResolvedPromptEnvelope.parse(data)
       });
       const raw = unwrap(envelope);
-      const result = normalizeResolvedEnvelope(raw);
-      const isWeighted = raw.strategy === "weighted" || result.variantName !== undefined;
-      const cacheable = !(isWeighted && subject === undefined);
-      if (useCache && cacheable) {
-        this.cache.set(cacheKey, structuredClone(result));
-      }
-      return result;
-    } catch (err) {
-      if (err instanceof To11aiNetworkError && fallback !== undefined) {
-        return liftFallbackToFetched(fallback);
-      }
-      throw err;
-    }
-  }
-  async resolve(input) {
-    const {
-      projectId,
-      slug,
-      labels,
-      variables,
-      cache: useCache = true,
-      fallback
-    } = input;
-    const cacheKey = buildCacheKey(projectId, slug, labels, variables);
-    if (useCache) {
-      const cached = this.cache.get(cacheKey);
-      if (cached && !("messages" in cached))
-        return structuredClone(cached);
-    }
-    try {
-      const envelope = await this.transport.request("POST", `${getProjectPromptsPath(projectId)}:resolve`, {
-        body: { slug, labels, variables },
-        decode: (data) => zResolvedPromptLegacy.parse(data)
-      });
-      const result = unwrap(envelope);
-      if (useCache) {
-        this.cache.set(cacheKey, structuredClone(result));
-      }
-      return result;
+      return normalizeResolvedEnvelope(raw, slug);
     } catch (err) {
-      if (err instanceof To11aiNetworkError && fallback !== undefined) {
-        return fallback;
+      const transient = err instanceof To11aiNetworkError || err instanceof To11aiApiError && err.statusCode >= 500;
+      if (transient && fallback !== undefined) {
+        return liftFallbackToRendered(fallback, slug);
       }
       throw err;
     }
   }
-  async listProjectLabels(input) {
-    const { projectId, includeArchived } = input;
+  async listProjectLabels(input = {}) {
+    const { projectId: perCallProjectId, includeArchived } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("GET", getProjectPromptLabelsPath(projectId), {
       query: includeArchived ? { includeArchived: "true" } : undefined
     });
     return unwrap(envelope);
   }
   async createProjectLabel(input) {
-    const { projectId, ...body } = input;
+    const { projectId: perCallProjectId, ...body } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const envelope = await this.transport.request("POST", getProjectPromptLabelsPath(projectId), { body });
     return unwrap(envelope);
   }
   async getProjectLabel(input) {
-    const envelope = await this.transport.request("GET", getProjectPromptLabelPath(input.projectId, input.label));
+    const projectId = this.resolveProjectId(input.projectId);
+    const envelope = await this.transport.request("GET", getProjectPromptLabelPath(projectId, input.label));
     return unwrap(envelope);
   }
   async updateProjectLabel(input) {
-    const { projectId, label, ...rest } = input;
+    const { projectId: perCallProjectId, label, ...rest } = input;
+    const projectId = this.resolveProjectId(perCallProjectId);
     const body = {};
     if (rest.isDefault !== undefined)
       body.isDefault = rest.isDefault;
@@ -276,15 +246,16 @@ class PromptResource {
     return unwrap(envelope);
   }
   async deleteProjectLabel(input) {
-    const envelope = await this.transport.request("DELETE", getProjectPromptLabelPath(input.projectId, input.label));
+    const projectId = this.resolveProjectId(input.projectId);
+    const envelope = await this.transport.request("DELETE", getProjectPromptLabelPath(projectId, input.label));
     return unwrap(envelope);
   }
   async listProjectLabelUsages(input) {
-    const envelope = await this.transport.request("GET", `${getProjectPromptLabelPath(input.projectId, input.label)}/usages`);
+    const envelope = await this.transport.request("GET", `${getProjectPromptLabelPath(this.resolveProjectId(input.projectId), input.label)}/usages`);
     return unwrap(envelope);
   }
   async listLabelEvents(input) {
-    const projectSeg = encodeURIComponent(input.projectId);
+    const projectSeg = encodeURIComponent(this.resolveProjectId(input.projectId));
     let path;
     switch (input.scope) {
       case "label":

package/dist/prompts/shape.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 } 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;
+    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;
+export declare function shapeOpenAI(prompt: RenderedPrompt, options?: ConvertMessagesOptions): OpenAiRenderedPrompt;
+export declare function shapeAnthropic(prompt: RenderedPrompt, options?: ConvertMessagesOptions): AnthropicRenderedPrompt;
+/** Shape a rendered prompt for `format`, or return it neutral when unset. */
+export declare function shapePrompt(prompt: RenderedPrompt, format: RenderFormat | undefined, options?: ConvertMessagesOptions): RenderedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt;

package/dist/prompts/types.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectPromptLabel as GenProjectPromptLabel, ProjectPromptLabelUsage as GenProjectPromptLabelUsage, Prompt as GenPrompt, PromptLabelEvent as GenPromptLabelEvent, PromptLabelPointer as GenPromptLabelPointer, PromptVersion as GenPromptVersion, RenderedChatPrompt as GenRenderedChatPrompt, RenderedPrompt as GenRenderedPrompt, ResolvedPrompt as GenResolvedPrompt, ResolvedToolCall as GenResolvedToolCall, ResolvedToolDefinition as GenResolvedToolDefinition } from "../generated/types.gen";
+import type { ProjectPromptLabel as GenProjectPromptLabel, ProjectPromptLabelUsage as GenProjectPromptLabelUsage, Prompt as GenPrompt, PromptLabelEvent as GenPromptLabelEvent, PromptLabelPointer as GenPromptLabelPointer, PromptVersion as GenPromptVersion, RenderedChatPrompt as GenRenderedChatPrompt, ResolvedPrompt as GenResolvedPrompt, ResolvedToolCall as GenResolvedToolCall, ResolvedToolDefinition as GenResolvedToolDefinition } from "../generated/types.gen";
 export interface RowError {
     path: ReadonlyArray<string | number>;
     code: string;
@@ -9,15 +9,23 @@ export type PromptStatus = Prompt["status"];
 export type PromptVersion = GenPromptVersion;
 export type PromptFormat = PromptVersion["format"];
 export type PromptLabelPointer = GenPromptLabelPointer;
-export type TextChatRole = "system" | "user" | "assistant" | "developer";
-export interface TextChatMessage {
-    role: TextChatRole;
+export type ChatRole = "system" | "user" | "assistant" | "developer";
+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 }`),
  * sourced from authored tool-definition blocks. Surfaced on the resolved
@@ -29,7 +37,7 @@ export type ResolvedToolDefinition = GenResolvedToolDefinition;
  * on a rendered `assistant` turn (few-shot multi-tool history).
  */
 export type ResolvedToolCall = GenResolvedToolCall;
-export type ResolvedPrompt = Pick<GenResolvedPrompt, "promptId" | "versionId" | "version" | "labels" | "contentHash" | "rendered" | "tools" | "toolChoice">;
+export type ResolvedPrompt = Pick<GenResolvedPrompt, "promptId" | "versionId" | "version" | "label" | "contentHash" | "rendered" | "tools" | "toolChoice" | "modelConfig">;
 export interface PaginationInfo {
     page: number;
     limit: number;
@@ -41,7 +49,7 @@ export interface PaginatedResult<T> {
     pagination: PaginationInfo;
 }
 export interface CreatePromptInput {
-    projectId: string;
+    projectId?: string;
     name: string;
     slug: string;
     description?: string;
@@ -49,7 +57,7 @@ export interface CreatePromptInput {
 }
 export type CreatePromptResult = Prompt;
 export interface ListPromptsInput {
-    projectId: string;
+    projectId?: string;
     status?: PromptStatus;
     sortBy?: "createdAt" | "updatedAt" | "name";
     tags?: string;
@@ -58,12 +66,12 @@ 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;
@@ -71,12 +79,12 @@ 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;
@@ -86,18 +94,18 @@ 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;
 }
 export type GetPromptVersionResult = PromptVersion;
 export interface MovePromptLabelInput {
-    projectId: string;
+    projectId?: string;
     promptId: string;
     label: string;
     versionId: string;
@@ -105,24 +113,20 @@ 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 declare const ENV_SLUG_REGEX: RegExp;
 export type BlockRenderRecord = Record<string, "rendered" | "dimmed">;
-export interface FetchedPrompt {
+export interface RenderedPrompt {
     messages: RenderedChatMessage[];
     version: number;
     releaseId: string | null;
@@ -131,8 +135,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
@@ -145,47 +165,42 @@ 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 interface FetchPromptOptions {
-    env?: string;
-    subject?: string;
+export type ResolvedPromptEnvelope = GenResolvedPrompt;
+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"];
 export type ProjectPromptLabel = GenProjectPromptLabel;
 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;
 }
 export type ListProjectPromptLabelsResult = ProjectPromptLabel[];
 export interface CreateProjectPromptLabelInput {
-    projectId: string;
+    projectId?: string;
     label: string;
     isDefault?: boolean;
     description?: string;
@@ -193,12 +208,12 @@ 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;
@@ -206,18 +221,18 @@ 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;
 }
 export type ListProjectPromptLabelUsagesResult = ProjectPromptLabelUsage[];
 export type ListLabelEventsInput = {
     scope: "label";
-    projectId: string;
+    projectId?: string;
     promptId: string;
     label: string;
     page?: number;
@@ -226,7 +241,7 @@ export type ListLabelEventsInput = {
     until?: string;
 } | {
     scope: "prompt";
-    projectId: string;
+    projectId?: string;
     promptId: string;
     label?: string;
     page?: number;
@@ -235,7 +250,7 @@ export type ListLabelEventsInput = {
     until?: string;
 } | {
     scope: "project";
-    projectId: string;
+    projectId?: string;
     promptId?: string;
     label?: string;
     page?: number;