@to11ai/sdk 1.0.0 → 2.0.0-rc.1

package/dist/prompts/cache.d.ts

@@ -7,7 +7,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;
 /**
@@ -24,7 +24,7 @@ export type CacheableResolved = ResolvedPrompt | FetchedPrompt;
  */
 export declare function buildCacheKey(projectId: string, slug: string, labels: string[], variables?: Record<string, unknown>): string;
 /**
- * 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
@@ -38,7 +38,7 @@ export declare function buildCacheKey(projectId: string, slug: string, labels: s
  * caches as the same deterministic variant on repeat (D8); the
  * weighted-no-subject bypass is handled in the resource, not here.
  */
-export declare function buildFetchCacheKey(projectId: string, slug: string, env: string, subject?: string, variables?: Record<string, unknown>, developerRole?: string): string;
+export declare function buildFetchCacheKey(projectId: string, slug: string, env: string, subject?: string, variables?: Record<string, unknown>): string;
 /**
  * In-memory LRU cache for ResolvedPrompt objects.
  *

package/dist/prompts/resource.cjs

@@ -46,16 +46,18 @@ var import_zod = require("zod");
 var import_errors = require("../errors");
 var import_zod2 = require("../generated/zod.gen");
 var import_cache = require("./cache");
+var import_shape = require("./shape");
 var import_types = require("./types");
 var zResolvedPromptLegacy = import_zod2.zResolvedPrompt.pick({
   promptId: true,
   versionId: true,
   version: true,
-  labels: true,
+  label: true,
   contentHash: true,
   rendered: true,
   tools: true,
-  toolChoice: true
+  toolChoice: true,
+  modelConfig: true
 });
 var zResolvedPromptEnvelope = import_zod2.zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: import_zod.z.enum(["single", "weighted"]).optional() });
 function unwrap(envelope) {
@@ -83,8 +85,9 @@ function normalizeResolvedEnvelope(raw) {
     promptId: raw.promptId,
     versionId: raw.versionId,
     contentHash: raw.contentHash,
-    labels: raw.labels,
-    rendered: raw.rendered
+    label: raw.label,
+    rendered: raw.rendered,
+    modelConfig: provenance.modelConfig
   };
   if (raw.tools != null && raw.tools.length > 0) {
     result.tools = raw.tools;
@@ -139,11 +142,15 @@ class PromptResource {
   cache;
   projectId;
   env;
+  format;
+  onUnknownRole;
   constructor(transport, cacheConfig, config) {
     this.transport = transport;
     this.cache = new import_cache.PromptCache(cacheConfig);
     this.projectId = config?.projectId;
     this.env = config?.env;
+    this.format = config?.format;
+    this.onUnknownRole = config?.onUnknownRole;
   }
   async create(input) {
     const { projectId, ...body } = input;
@@ -207,9 +214,15 @@ class PromptResource {
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
     return unwrap(envelope);
   }
-  async fetch(slug, options = {}) {
+  async render(slug, options = {}) {
+    const fetched = await this.resolveToFetched(slug, options);
+    return import_shape.shapePrompt(fetched, options.format ?? this.format, {
+      onUnknownRole: options.onUnknownRole ?? this.onUnknownRole
+    });
+  }
+  async resolveToFetched(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) {
@@ -218,14 +231,8 @@ class PromptResource {
     if (!import_types.ENV_SLUG_REGEX.test(env)) {
       throw new Error(`[to11ai/sdk] \`env\` must match ${import_types.ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`);
     }
-    const {
-      subject,
-      variables,
-      cache: useCache = true,
-      fallback,
-      developerRole
-    } = options;
-    const cacheKey = import_cache.buildFetchCacheKey(this.projectId, slug, env, subject, variables, developerRole);
+    const { subject, variables, cache: useCache = true, fallback } = options;
+    const cacheKey = import_cache.buildFetchCacheKey(this.projectId, slug, env, subject, variables);
     if (useCache) {
       const cached = this.cache.get(cacheKey);
       if (cached && "messages" in cached)
@@ -236,8 +243,6 @@ class PromptResource {
       body.subject = subject;
     if (variables !== undefined)
       body.variables = variables;
-    if (developerRole !== undefined)
-      body.developerRole = developerRole;
     try {
       const envelope = await this.transport.request("POST", `${getProjectPromptsPath(this.projectId)}:resolve`, {
         body,

package/dist/prompts/resource.d.ts

@@ -1,27 +1,39 @@
 import type { Transport } from "../transport";
 import type { CacheConfig } from "./cache";
-import type { ArchivePromptInput, ArchivePromptResult, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, FetchedPrompt, FetchPromptOptions, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, ResolvePromptInput, ResolvePromptResult, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult } from "./types";
+import type { AnthropicRenderedPrompt, OpenAiRenderedPrompt, RenderResult } from "./shape";
+import type { ArchivePromptInput, ArchivePromptResult, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, RenderFormat, RenderOptions, ResolvePromptInput, ResolvePromptResult, UnknownRoleMode, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult } from "./types";
 export type { CacheConfig } from "./cache";
 export type { ArchivePromptInput, ArchivePromptResult, BlockRenderRecord, ChatMessage, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, FetchedPrompt, FetchPromptOptions, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, PaginationInfo, PaletteToken, ProjectPromptLabel, ProjectPromptLabelUsage, Prompt, PromptFormat, PromptLabelEvent, PromptLabelPointer, PromptStatus, PromptVersion, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvedPromptEnvelope, ResolvedToolCall, ResolvedToolDefinition, ResolvePromptInput, ResolvePromptResult, RowError, TextChatMessage, TextChatRole, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult, } from "./types";
 /**
- * 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 declare class PromptResource {
+export declare class PromptResource<F extends RenderFormat | undefined = undefined> {
     private readonly transport;
     private readonly cache;
     private readonly projectId;
     private readonly env;
-    constructor(transport: Transport, cacheConfig?: CacheConfig, config?: PromptResourceConfig);
+    private readonly format;
+    private readonly onUnknownRole;
+    constructor(transport: Transport, cacheConfig?: CacheConfig, config?: Omit<PromptResourceConfig, "format"> & {
+        format?: F;
+    });
     create(input: CreatePromptInput): Promise<CreatePromptResult>;
     list(input: ListPromptsInput): Promise<PaginatedResult<ListPromptsResult>>;
     get(input: GetPromptInput): Promise<GetPromptResult>;
@@ -33,33 +45,52 @@ export declare class PromptResource {
     moveLabel(input: MovePromptLabelInput): Promise<MovePromptLabelResult>;
     listLabels(input: ListPromptLabelsInput): Promise<ListPromptLabelsResult>;
     /**
-     * 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.
+     * 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) },
+     * );
+     */
+    render(slug: string, options: RenderOptions & {
+        format: "openai";
+    }): Promise<OpenAiRenderedPrompt>;
+    render(slug: string, options: RenderOptions & {
+        format: "anthropic";
+    }): Promise<AnthropicRenderedPrompt>;
+    render(slug: string, options?: RenderOptions): Promise<RenderResult<F>>;
+    /**
+     * 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()`.
      */
-    fetch(slug: string, options?: FetchPromptOptions): Promise<FetchedPrompt>;
+    private resolveToFetched;
     /**
-     * @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.
      */
     resolve(input: ResolvePromptInput): Promise<ResolvePromptResult>;
     /**

package/dist/prompts/resource.js

@@ -3,16 +3,18 @@ import { z } from "zod";
 import { EnvNotFoundError, 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,
+  label: true,
   contentHash: true,
   rendered: true,
   tools: true,
-  toolChoice: true
+  toolChoice: true,
+  modelConfig: true
 });
 var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: z.enum(["single", "weighted"]).optional() });
 function unwrap(envelope) {
@@ -40,8 +42,9 @@ function normalizeResolvedEnvelope(raw) {
     promptId: raw.promptId,
     versionId: raw.versionId,
     contentHash: raw.contentHash,
-    labels: raw.labels,
-    rendered: raw.rendered
+    label: raw.label,
+    rendered: raw.rendered,
+    modelConfig: provenance.modelConfig
   };
   if (raw.tools != null && raw.tools.length > 0) {
     result.tools = raw.tools;
@@ -96,11 +99,15 @@ class PromptResource {
   cache;
   projectId;
   env;
+  format;
+  onUnknownRole;
   constructor(transport, cacheConfig, 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;
   }
   async create(input) {
     const { projectId, ...body } = input;
@@ -164,9 +171,15 @@ class PromptResource {
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
     return unwrap(envelope);
   }
-  async fetch(slug, options = {}) {
+  async render(slug, options = {}) {
+    const fetched = await this.resolveToFetched(slug, options);
+    return shapePrompt(fetched, options.format ?? this.format, {
+      onUnknownRole: options.onUnknownRole ?? this.onUnknownRole
+    });
+  }
+  async resolveToFetched(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) {
@@ -175,14 +188,8 @@ class PromptResource {
     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)}`);
     }
-    const {
-      subject,
-      variables,
-      cache: useCache = true,
-      fallback,
-      developerRole
-    } = options;
-    const cacheKey = buildFetchCacheKey(this.projectId, slug, env, subject, variables, developerRole);
+    const { subject, variables, cache: useCache = true, fallback } = options;
+    const cacheKey = buildFetchCacheKey(this.projectId, slug, env, subject, variables);
     if (useCache) {
       const cached = this.cache.get(cacheKey);
       if (cached && "messages" in cached)
@@ -193,8 +200,6 @@ class PromptResource {
       body.subject = subject;
     if (variables !== undefined)
       body.variables = variables;
-    if (developerRole !== undefined)
-      body.developerRole = developerRole;
     try {
       const envelope = await this.transport.request("POST", `${getProjectPromptsPath(this.projectId)}:resolve`, {
         body,

package/dist/prompts/shape.d.ts

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

package/dist/prompts/types.d.ts

@@ -18,6 +18,16 @@ export interface TextChatMessage {
 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 +39,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;
@@ -131,8 +141,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
@@ -154,25 +175,22 @@ 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;
     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"];
 export type ProjectPromptLabel = GenProjectPromptLabel;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@to11ai/sdk",
-	"version": "1.0.0",
+	"version": "2.0.0-rc.1",
 	"license": "MPL-2.0",
 	"repository": {
 		"type": "git",