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

package/dist/client.cjs

@@ -108,7 +108,7 @@ function createClient(options = {}) {
   const getAccessToken = options.getAccessToken;
   const apiKey = getAccessToken !== undefined ? options.apiKey : pick(options.apiKey, "TO11_API_KEY");
   const projectId = pick(options.projectId, "TO11_PROJECT_ID");
-  const env = options.env;
+  const env = pick(options.env, "TO11_ENV");
   const providerApiKey = options.providerApiKey?.trim() || undefined;
   if (isBrowser && options.apiKey !== undefined) {
     throw new Error("[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.");
@@ -119,6 +119,9 @@ function createClient(options = {}) {
   if (options.projectId !== undefined && options.projectId.trim() === "") {
     throw new Error("[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.");
   }
+  if (options.env !== undefined && options.env.trim() === "") {
+    throw new Error("[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.");
+  }
   if (env !== undefined && !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)}`);
   }

package/dist/client.d.ts

@@ -17,7 +17,7 @@ export type { CacheConfig } from "./prompts/cache";
 export type { PromptResourceConfig } from "./prompts/resource";
 export { PromptResource } from "./prompts/resource";
 export type { AnthropicRenderedPrompt, OpenAiRenderedPrompt, PromptConfig, PromptMetadata, RenderResult, } from "./prompts/shape";
-export type { BlockRenderRecord, FetchedPrompt, FetchPromptOptions, RenderedChatMessage, RenderedPrompt, RenderFormat, RenderOptions, ResolvedPrompt, ResolvedPromptEnvelope, UnknownRoleMode, } from "./prompts/types";
+export type { BlockRenderRecord, RenderedChatMessage, RenderedPrompt, RenderFormat, RenderOptions, ResolvedPrompt, ResolvedPromptEnvelope, UnknownRoleMode, } from "./prompts/types";
 export { ENV_SLUG_REGEX } from "./prompts/types";
 export type { CreateRuleVersionInput, CreateRuleVersionResult, GetRuleVersionInput, GetRuleVersionResult, ListRuleReleasesInput, ListRuleReleasesResult, ListRuleVersionsInput, ListRuleVersionsResult, RollbackRuleReleaseInput, RollbackRuleReleaseResult, RuleModelBinding, RuleProviderRef, RuleRelease, RuleReleaseActorType, RuleReleaseApprovalStatus, RuleReleaseChangeKind, RuleReleaseStrategy, RuleReleaseWeight, RuleSnapshot, RuleStrategy, RuleVersion, SetRuleReleaseInput, SetRuleReleaseResult, } from "./routingRules/resource";
 export { RoutingRuleReleaseResource, RoutingRulesResource, RoutingRuleVersionResource, } from "./routingRules/resource";
@@ -57,8 +57,9 @@ export interface ClientOptions {
     projectId?: string;
     /**
      * Default serving environment for `prompts.render(slug)`, inherited by every
-     * render unless overridden per call. Validated eagerly against the
-     * project-environments slug rule (`^[a-z0-9-]{1,63}$`).
+     * render unless overridden per call. Precedence: this option → `TO11_ENV`
+     * env. Validated eagerly against the project-environments slug rule
+     * (`^[a-z0-9-]{1,63}$`).
      */
     env?: string;
     /**

package/dist/client.js

@@ -64,7 +64,7 @@ function createClient(options = {}) {
   const getAccessToken = options.getAccessToken;
   const apiKey = getAccessToken !== undefined ? options.apiKey : pick(options.apiKey, "TO11_API_KEY");
   const projectId = pick(options.projectId, "TO11_PROJECT_ID");
-  const env = options.env;
+  const env = pick(options.env, "TO11_ENV");
   const providerApiKey = options.providerApiKey?.trim() || undefined;
   if (isBrowser && options.apiKey !== undefined) {
     throw new Error("[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.");
@@ -75,6 +75,9 @@ function createClient(options = {}) {
   if (options.projectId !== undefined && options.projectId.trim() === "") {
     throw new Error("[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.");
   }
+  if (options.env !== undefined && options.env.trim() === "") {
+    throw new Error("[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.");
+  }
   if (env !== undefined && !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)}`);
   }

package/dist/context.d.ts

@@ -17,7 +17,7 @@ export interface TurnAuthContext {
 }
 /**
  * A prompt argument accepted by `turn.headers()`. Either the flat provenance
- * (a neutral `FetchedPrompt`) or a `format`-shaped result carrying it under
+ * (a neutral `RenderedPrompt`) or a `format`-shaped result carrying it under
  * `metadata` — both are accepted so the format and neutral render paths carry
  * provenance identically.
  */

package/dist/gateway.cjs

@@ -88,6 +88,9 @@ function gatewayPromptHeaders(prompt) {
   if (prompt.label.length > 0) {
     headers["x-to11-prompt-label"] = prompt.label;
   }
+  if (typeof prompt.slug === "string" && prompt.slug.length > 0) {
+    headers["x-to11-prompt-slug"] = prompt.slug;
+  }
   return headers;
 }
 function toOpenAITools(tools) {

package/dist/gateway.d.ts

@@ -42,6 +42,9 @@ export declare function gatewayAuthHeaders(options: GatewayAuthOptions): Record<
  *     release was weighted); omitted for `single`-strategy releases.
  *   - `x-to11-prompt-label` — the single label the prompt resolved through (the
  *     env slug today); omitted when empty (the gateway rejects empty values).
+ *   - `x-to11-prompt-slug` — the prompt's human-readable slug, so traces show a
+ *     readable name alongside the opaque `x-to11-prompt-id`; omitted when empty
+ *     or absent (a legacy `resolve()` result carries no slug).
  *
  * The parameter type is WIDENED to accept either the enriched `render()`
  * result or the legacy `ResolvedPrompt`. The new fields are read when present
@@ -57,6 +60,11 @@ export interface GatewayPromptProvenance {
     version: number;
     /** The single label the prompt resolved through (env slug today). */
     label: string;
+    /**
+     * The prompt's human-readable slug (the `render()`/`resolve()` input). Present
+     * on an enriched `render()` result; a legacy `ResolvedPrompt` omits it.
+     */
+    slug?: string;
     /** Present on an enriched result; a legacy `resolve()` result omits it. */
     releaseId?: string | null;
     /** Present IFF the resolved release was weighted. */

package/dist/gateway.js

@@ -39,6 +39,9 @@ function gatewayPromptHeaders(prompt) {
   if (prompt.label.length > 0) {
     headers["x-to11-prompt-label"] = prompt.label;
   }
+  if (typeof prompt.slug === "string" && prompt.slug.length > 0) {
+    headers["x-to11-prompt-slug"] = prompt.slug;
+  }
   return headers;
 }
 function toOpenAITools(tools) {

package/dist/prompts/cache.d.ts

@@ -1,4 +1,4 @@
-import type { FetchedPrompt, ResolvedPrompt } from "./types";
+import type { RenderedPrompt } from "./types";
 export interface CacheConfig {
     /** Time-to-live in seconds. Default: 300 (5 minutes) */
     ttlSeconds?: number;
@@ -6,12 +6,11 @@ export interface CacheConfig {
     maxEntries?: number;
 }
 /**
- * The cache stores either a legacy `resolve()` result or an enriched
- * `render()` result. Both are JSON-cloneable; the cache is shape-agnostic.
+ * The cache stores enriched `render()` results, which are JSON-cloneable.
  */
-export type CacheableResolved = ResolvedPrompt | FetchedPrompt;
+export type CacheableRendered = RenderedPrompt;
 /**
- * Build a canonical cache key for a resolve() call.
+ * Build a canonical base cache key from project/slug/labels/variables.
  *
  * - projectId is included to prevent cross-project cache collisions: a single
  *   PromptResource can serve multiple projects, so the same slug+labels must
@@ -38,9 +37,9 @@ 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>): string;
+export declare function buildRenderCacheKey(projectId: string, slug: string, env: string, subject?: string, variables?: Record<string, unknown>): string;
 /**
- * In-memory LRU cache for ResolvedPrompt objects.
+ * In-memory LRU cache for RenderedPrompt objects.
  *
  * Uses a Map (insertion-ordered) as the backing store. On every access, the
  * entry is deleted and re-inserted to maintain LRU order — oldest entries sit
@@ -51,8 +50,8 @@ export declare class PromptCache {
     private readonly maxEntries;
     private readonly store;
     constructor(config?: CacheConfig);
-    get(key: string): CacheableResolved | undefined;
-    set(key: string, value: CacheableResolved): void;
+    get(key: string): CacheableRendered | undefined;
+    set(key: string, value: CacheableRendered): void;
     delete(key: string): void;
     clear(): void;
     get size(): number;

package/dist/prompts/resource.cjs

@@ -48,17 +48,6 @@ 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,
-  label: true,
-  contentHash: true,
-  rendered: true,
-  tools: 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) {
   if (envelope.data === null || envelope.data === undefined) {
@@ -70,12 +59,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),
@@ -86,7 +75,7 @@ function normalizeResolvedEnvelope(raw) {
     versionId: raw.versionId,
     contentHash: raw.contentHash,
     label: raw.label,
-    rendered: raw.rendered,
+    slug,
     modelConfig: provenance.modelConfig
   };
   if (raw.tools != null && raw.tools.length > 0) {
@@ -100,11 +89,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)}`;
@@ -215,12 +204,12 @@ class PromptResource {
     return unwrap(envelope);
   }
   async render(slug, options = {}) {
-    const fetched = await this.resolveToFetched(slug, options);
-    return import_shape.shapePrompt(fetched, options.format ?? this.format, {
+    const rendered = await this.resolveToRendered(slug, options);
+    return import_shape.shapePrompt(rendered, options.format ?? this.format, {
       onUnknownRole: options.onUnknownRole ?? this.onUnknownRole
     });
   }
-  async resolveToFetched(slug, options = {}) {
+  async resolveToRendered(slug, options = {}) {
     if (this.projectId === undefined || this.projectId.trim() === "") {
       throw new Error("[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).");
     }
@@ -232,10 +221,10 @@ class PromptResource {
       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 } = options;
-    const cacheKey = import_cache.buildFetchCacheKey(this.projectId, slug, env, subject, variables);
+    const cacheKey = import_cache.buildRenderCacheKey(this.projectId, slug, env, subject, variables);
     if (useCache) {
       const cached = this.cache.get(cacheKey);
-      if (cached && "messages" in cached)
+      if (cached)
         return structuredClone(cached);
     }
     const body = { slug, labels: [env] };
@@ -249,7 +238,7 @@ class PromptResource {
         decode: (data) => zResolvedPromptEnvelope.parse(data)
       });
       const raw = unwrap(envelope);
-      const result = normalizeResolvedEnvelope(raw);
+      const result = normalizeResolvedEnvelope(raw, slug);
       const isWeighted = raw.strategy === "weighted" || result.variantName !== undefined;
       const cacheable = !(isWeighted && subject === undefined);
       if (useCache && cacheable) {
@@ -258,39 +247,7 @@ class PromptResource {
       return result;
     } catch (err) {
       if (err instanceof import_errors.To11aiNetworkError && fallback !== undefined) {
-        return liftFallbackToFetched(fallback);
-      }
-      throw err;
-    }
-  }
-  async resolve(input) {
-    const {
-      projectId,
-      slug,
-      labels,
-      variables,
-      cache: useCache = true,
-      fallback
-    } = input;
-    const cacheKey = import_cache.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;
-    } catch (err) {
-      if (err instanceof import_errors.To11aiNetworkError && fallback !== undefined) {
-        return fallback;
+        return liftFallbackToRendered(fallback, slug);
       }
       throw err;
     }

package/dist/prompts/resource.d.ts

@@ -1,9 +1,9 @@
 import type { Transport } from "../transport";
 import type { CacheConfig } from "./cache";
 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";
+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, 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";
+export type { ArchivePromptInput, ArchivePromptResult, BlockRenderRecord, ChatMessage, 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, PaginationInfo, PaletteToken, ProjectPromptLabel, ProjectPromptLabelUsage, Prompt, PromptFormat, PromptLabelEvent, PromptLabelPointer, PromptStatus, PromptVersion, RenderedChatMessage, RenderedPrompt, RenderFormat, RenderOptions, ResolvedPrompt, ResolvedPromptEnvelope, ResolvedToolCall, ResolvedToolDefinition, RowError, TextChatMessage, TextChatRole, UnknownRoleMode, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult, } from "./types";
 /**
  * Init-time config for the env-aware `render()` surface (TO11-980 / S9).
  *
@@ -49,8 +49,7 @@ export declare class PromptResource<F extends RenderFormat | undefined = undefin
      * `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()`}.
+     * `RenderedPrompt`. Resolves by the client's configured `env`.
      *
      * @example Render an OpenAI-shaped prompt and send it through the gateway
      * const prompt = await to11.prompts.render("weather-concierge", {
@@ -69,7 +68,7 @@ export declare class PromptResource<F extends RenderFormat | undefined = undefin
     }): Promise<AnthropicRenderedPrompt>;
     render(slug: string, options?: RenderOptions): Promise<RenderResult<F>>;
     /**
-     * Env-aware resolution → neutral `FetchedPrompt`. Carries the resolve /
+     * Env-aware resolution → neutral `RenderedPrompt`. Carries the resolve /
      * cache / offline-fallback logic; `render()` is the public shaping surface.
      *
      * - **env→label wire mapping:** the resolve route is label-based
@@ -82,17 +81,7 @@ export declare class PromptResource<F extends RenderFormat | undefined = undefin
      *   WITH a `subject`; BYPASSES the cache for weighted releases with NO
      *   `subject` (a uniform-random assignment must not be pinned for the TTL).
      */
-    private resolveToFetched;
-    /**
-     * 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>;
+    private resolveToRendered;
     /**
      * List the project-level label registry.
      *

package/dist/prompts/resource.js

@@ -2,20 +2,9 @@
 import { z } from "zod";
 import { EnvNotFoundError, To11aiNetworkError } from "../errors";
 import { zResolvedPrompt } from "../generated/zod.gen";
-import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
+import { buildRenderCacheKey, PromptCache } from "./cache";
 import { shapePrompt } from "./shape";
 import { ENV_SLUG_REGEX } from "./types";
-var zResolvedPromptLegacy = zResolvedPrompt.pick({
-  promptId: true,
-  versionId: true,
-  version: true,
-  label: true,
-  contentHash: true,
-  rendered: true,
-  tools: true,
-  toolChoice: true,
-  modelConfig: true
-});
 var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: z.enum(["single", "weighted"]).optional() });
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
@@ -27,12 +16,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),
@@ -43,7 +32,7 @@ function normalizeResolvedEnvelope(raw) {
     versionId: raw.versionId,
     contentHash: raw.contentHash,
     label: raw.label,
-    rendered: raw.rendered,
+    slug,
     modelConfig: provenance.modelConfig
   };
   if (raw.tools != null && raw.tools.length > 0) {
@@ -57,11 +46,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)}`;
@@ -172,12 +161,12 @@ class PromptResource {
     return unwrap(envelope);
   }
   async render(slug, options = {}) {
-    const fetched = await this.resolveToFetched(slug, options);
-    return shapePrompt(fetched, options.format ?? this.format, {
+    const rendered = await this.resolveToRendered(slug, options);
+    return shapePrompt(rendered, options.format ?? this.format, {
       onUnknownRole: options.onUnknownRole ?? this.onUnknownRole
     });
   }
-  async resolveToFetched(slug, options = {}) {
+  async resolveToRendered(slug, options = {}) {
     if (this.projectId === undefined || this.projectId.trim() === "") {
       throw new Error("[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).");
     }
@@ -189,10 +178,10 @@ class PromptResource {
       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 } = options;
-    const cacheKey = buildFetchCacheKey(this.projectId, slug, env, subject, variables);
+    const cacheKey = buildRenderCacheKey(this.projectId, slug, env, subject, variables);
     if (useCache) {
       const cached = this.cache.get(cacheKey);
-      if (cached && "messages" in cached)
+      if (cached)
         return structuredClone(cached);
     }
     const body = { slug, labels: [env] };
@@ -206,7 +195,7 @@ class PromptResource {
         decode: (data) => zResolvedPromptEnvelope.parse(data)
       });
       const raw = unwrap(envelope);
-      const result = normalizeResolvedEnvelope(raw);
+      const result = normalizeResolvedEnvelope(raw, slug);
       const isWeighted = raw.strategy === "weighted" || result.variantName !== undefined;
       const cacheable = !(isWeighted && subject === undefined);
       if (useCache && cacheable) {
@@ -215,39 +204,7 @@ class PromptResource {
       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;
-    } catch (err) {
-      if (err instanceof To11aiNetworkError && fallback !== undefined) {
-        return fallback;
+        return liftFallbackToRendered(fallback, slug);
       }
       throw err;
     }

package/dist/prompts/shape.d.ts

@@ -1,11 +1,11 @@
 /**
- * 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.
  */
 import { type AnthropicMessage, type AnthropicTool, type AnthropicToolChoice, type ConvertMessagesOptions, type OpenAIChatMessage, type OpenAITool, type OpenAIToolChoice } 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 {
     model?: string;
@@ -22,6 +22,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;
 }
 /** OpenAI-shaped render result: spread `{ ...config, messages }` into create(). */
@@ -47,8 +49,8 @@ export interface AnthropicRenderedPrompt {
     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;
+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 fetched prompt for `format`, or return it neutral when unset. */
-export declare function shapePrompt(prompt: FetchedPrompt, format: RenderFormat | undefined, options?: ConvertMessagesOptions): FetchedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt;
+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;
@@ -17,7 +17,6 @@ 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";
 /**
@@ -119,20 +118,9 @@ export interface ListPromptLabelsInput {
     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 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;
@@ -147,7 +135,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 })`.
@@ -166,7 +159,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"]>;
@@ -175,14 +168,16 @@ export type ResolvedPromptEnvelope = GenResolvedPrompt & {
     /** Active release strategy. Used to decide weighted-no-subject cache bypass (D8). */
     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;
     /**

package/package.json

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

package/src/client.ts

@@ -88,8 +88,6 @@ export type {
 // TO11-980 (S9): env-aware render() surface types at the package entrypoint (AC9).
 export type {
 	BlockRenderRecord,
-	FetchedPrompt,
-	FetchPromptOptions,
 	RenderedChatMessage,
 	RenderedPrompt,
 	RenderFormat,
@@ -168,8 +166,9 @@ export interface ClientOptions {
 	projectId?: string;
 	/**
 	 * Default serving environment for `prompts.render(slug)`, inherited by every
-	 * render unless overridden per call. Validated eagerly against the
-	 * project-environments slug rule (`^[a-z0-9-]{1,63}$`).
+	 * render unless overridden per call. Precedence: this option → `TO11_ENV`
+	 * env. Validated eagerly against the project-environments slug rule
+	 * (`^[a-z0-9-]{1,63}$`).
 	 */
 	env?: string;
 	/**
@@ -376,7 +375,12 @@ export function createClient<
 			? options.apiKey
 			: pick(options.apiKey, "TO11_API_KEY");
 	const projectId = pick(options.projectId, "TO11_PROJECT_ID");
-	const env = options.env;
+	// Default serving env: explicit option → `TO11_ENV` env var — the same
+	// `pick(option, "TO11_*")` resolution `apiKey`/`projectId` use (empty option
+	// or empty env var trims to absent). An explicit empty option is rejected by
+	// the dedicated guard below (mirroring `apiKey`/`projectId`); a non-empty but
+	// malformed value fails the `ENV_SLUG_REGEX` check.
+	const env = pick(options.env, "TO11_ENV");
 	// Provider (BYOK) key — option only, no env fallback (which provider's env
 	// var is ambiguous). Empty trims to absent so it falls back to the placeholder.
 	const providerApiKey = options.providerApiKey?.trim() || undefined;
@@ -398,6 +402,11 @@ export function createClient<
 			"[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.",
 		);
 	}
+	if (options.env !== undefined && options.env.trim() === "") {
+		throw new Error(
+			"[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.",
+		);
+	}
 
 	// Validate the init-time `env` against the project-environments slug rule so
 	// a malformed env fails locally rather than round-tripping to ENV_NOT_FOUND.

package/src/context.ts

@@ -24,7 +24,7 @@ export interface TurnAuthContext {
 
 /**
  * A prompt argument accepted by `turn.headers()`. Either the flat provenance
- * (a neutral `FetchedPrompt`) or a `format`-shaped result carrying it under
+ * (a neutral `RenderedPrompt`) or a `format`-shaped result carrying it under
  * `metadata` — both are accepted so the format and neutral render paths carry
  * provenance identically.
  */

package/src/gateway.ts

@@ -85,6 +85,9 @@ export function gatewayAuthHeaders(
  *     release was weighted); omitted for `single`-strategy releases.
  *   - `x-to11-prompt-label` — the single label the prompt resolved through (the
  *     env slug today); omitted when empty (the gateway rejects empty values).
+ *   - `x-to11-prompt-slug` — the prompt's human-readable slug, so traces show a
+ *     readable name alongside the opaque `x-to11-prompt-id`; omitted when empty
+ *     or absent (a legacy `resolve()` result carries no slug).
  *
  * The parameter type is WIDENED to accept either the enriched `render()`
  * result or the legacy `ResolvedPrompt`. The new fields are read when present
@@ -100,6 +103,11 @@ export interface GatewayPromptProvenance {
 	version: number;
 	/** The single label the prompt resolved through (env slug today). */
 	label: string;
+	/**
+	 * The prompt's human-readable slug (the `render()`/`resolve()` input). Present
+	 * on an enriched `render()` result; a legacy `ResolvedPrompt` omits it.
+	 */
+	slug?: string;
 	/** Present on an enriched result; a legacy `resolve()` result omits it. */
 	releaseId?: string | null;
 	/** Present IFF the resolved release was weighted. */
@@ -127,6 +135,11 @@ export function gatewayPromptHeaders(
 	if (prompt.label.length > 0) {
 		headers["x-to11-prompt-label"] = prompt.label;
 	}
+	// The prompt's human-readable slug. Omit when absent/empty — a legacy
+	// `resolve()` result carries no slug, and the gateway rejects empty values.
+	if (typeof prompt.slug === "string" && prompt.slug.length > 0) {
+		headers["x-to11-prompt-slug"] = prompt.slug;
+	}
 	return headers;
 }
 

package/src/generated/zod.gen.ts

@@ -236,7 +236,7 @@ export const zPrompt = z.object({
     id: z.string(),
     name: z.string().min(1).max(200),
     projectId: z.string(),
-    slug: z.string().min(1).max(200).regex(/^[a-z0-9-]+$/),
+    slug: z.string().min(1).max(128).regex(/^[a-z0-9-]+$/),
     status: z.enum(['active', 'archived']),
     tags: z.array(z.string()),
     updatedAt: z.iso.datetime()
@@ -7359,7 +7359,7 @@ export const zPromptsListPromptsResponse = z.object({
         latestVersion: z.number().nullable(),
         name: z.string().min(1).max(200),
         projectId: z.string(),
-        slug: z.string().min(1).max(200).regex(/^[a-z0-9-]+$/),
+        slug: z.string().min(1).max(128).regex(/^[a-z0-9-]+$/),
         status: z.enum(['active', 'archived']),
         tags: z.array(z.string()),
         updatedAt: z.iso.datetime()
@@ -7390,7 +7390,7 @@ export const zPromptsListPromptsResponse = z.object({
 export const zPromptsCreatePromptBody = z.object({
     description: z.string().nullish(),
     name: z.string().min(1).max(200),
-    slug: z.string().min(1).max(200).regex(/^[a-z0-9-]+$/),
+    slug: z.string().min(1).max(128).regex(/^[a-z0-9-]+$/),
     tags: z.array(z.string()).nullish()
 });
 

package/src/prompts/cache.ts

@@ -1,4 +1,4 @@
-import type { FetchedPrompt, ResolvedPrompt } from "./types";
+import type { RenderedPrompt } from "./types";
 
 export interface CacheConfig {
 	/** Time-to-live in seconds. Default: 300 (5 minutes) */
@@ -8,18 +8,17 @@ export interface CacheConfig {
 }
 
 /**
- * The cache stores either a legacy `resolve()` result or an enriched
- * `render()` result. Both are JSON-cloneable; the cache is shape-agnostic.
+ * The cache stores enriched `render()` results, which are JSON-cloneable.
  */
-export type CacheableResolved = ResolvedPrompt | FetchedPrompt;
+export type CacheableRendered = RenderedPrompt;
 
 interface CacheEntry {
-	value: CacheableResolved;
+	value: CacheableRendered;
 	expiresAt: number;
 }
 
 /**
- * Build a canonical cache key for a resolve() call.
+ * Build a canonical base cache key from project/slug/labels/variables.
  *
  * - projectId is included to prevent cross-project cache collisions: a single
  *   PromptResource can serve multiple projects, so the same slug+labels must
@@ -58,7 +57,7 @@ export function buildCacheKey(
  * caches as the same deterministic variant on repeat (D8); the
  * weighted-no-subject bypass is handled in the resource, not here.
  */
-export function buildFetchCacheKey(
+export function buildRenderCacheKey(
 	projectId: string,
 	slug: string,
 	env: string,
@@ -66,7 +65,7 @@ export function buildFetchCacheKey(
 	variables?: Record<string, unknown>,
 ): string {
 	const base = buildCacheKey(projectId, slug, [env], variables);
-	return `fetch|${base}|${JSON.stringify(env)}|${JSON.stringify(subject ?? null)}`;
+	return `render|${base}|${JSON.stringify(env)}|${JSON.stringify(subject ?? null)}`;
 }
 
 function sortObjectKeys(obj: unknown): unknown {
@@ -80,7 +79,7 @@ function sortObjectKeys(obj: unknown): unknown {
 }
 
 /**
- * In-memory LRU cache for ResolvedPrompt objects.
+ * In-memory LRU cache for RenderedPrompt objects.
  *
  * Uses a Map (insertion-ordered) as the backing store. On every access, the
  * entry is deleted and re-inserted to maintain LRU order — oldest entries sit
@@ -97,7 +96,7 @@ export class PromptCache {
 		this.store = new Map();
 	}
 
-	get(key: string): CacheableResolved | undefined {
+	get(key: string): CacheableRendered | undefined {
 		const entry = this.store.get(key);
 		if (!entry) return undefined;
 
@@ -113,7 +112,7 @@ export class PromptCache {
 		return entry.value;
 	}
 
-	set(key: string, value: CacheableResolved): void {
+	set(key: string, value: CacheableRendered): void {
 		// maxEntries: 0 (or negative) means caching is disabled — drop the entry.
 		if (this.maxEntries <= 0) {
 			return;

package/src/prompts/resource.ts

@@ -3,7 +3,7 @@ import { EnvNotFoundError, To11aiNetworkError } from "../errors";
 import { zResolvedPrompt } from "../generated/zod.gen";
 import type { ApiEnvelope, Transport } from "../transport";
 import type { CacheConfig } from "./cache";
-import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
+import { buildRenderCacheKey, PromptCache } from "./cache";
 import type {
 	AnthropicRenderedPrompt,
 	OpenAiRenderedPrompt,
@@ -21,8 +21,6 @@ import type {
 	CreatePromptVersionResult,
 	DeleteProjectPromptLabelInput,
 	DeleteProjectPromptLabelResult,
-	FetchedPrompt,
-	FetchPromptOptions,
 	GetProjectPromptLabelInput,
 	GetProjectPromptLabelResult,
 	GetPromptInput,
@@ -50,8 +48,6 @@ import type {
 	RenderOptions,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
-	ResolvePromptInput,
-	ResolvePromptResult,
 	UnknownRoleMode,
 	UpdateProjectPromptLabelInput,
 	UpdateProjectPromptLabelResult,
@@ -75,8 +71,6 @@ export type {
 	CreatePromptVersionResult,
 	DeleteProjectPromptLabelInput,
 	DeleteProjectPromptLabelResult,
-	FetchedPrompt,
-	FetchPromptOptions,
 	GetProjectPromptLabelInput,
 	GetProjectPromptLabelResult,
 	GetPromptInput,
@@ -110,33 +104,22 @@ export type {
 	PromptVersion,
 	RenderedChatMessage,
 	RenderedPrompt,
+	RenderFormat,
+	RenderOptions,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
 	ResolvedToolCall,
 	ResolvedToolDefinition,
-	ResolvePromptInput,
-	ResolvePromptResult,
 	RowError,
 	TextChatMessage,
 	TextChatRole,
+	UnknownRoleMode,
 	UpdateProjectPromptLabelInput,
 	UpdateProjectPromptLabelResult,
 	UpdatePromptInput,
 	UpdatePromptResult,
 } from "./types";
 
-const zResolvedPromptLegacy = zResolvedPrompt.pick({
-	promptId: true,
-	versionId: true,
-	version: true,
-	label: true,
-	contentHash: true,
-	rendered: true,
-	tools: true,
-	toolChoice: true,
-	modelConfig: true,
-});
-
 const zResolvedPromptEnvelope = zResolvedPrompt
 	.partial({ releaseId: true })
 	.extend({ strategy: z.enum(["single", "weighted"]).optional() });
@@ -153,22 +136,28 @@ function getProjectPromptsPath(projectId: string): string {
 }
 
 /**
- * Project a server `rendered` payload into the `messages` array of the R5
- * `FetchedPrompt` (D5):
- *   - `format: "chat"` → the message array directly.
- *   - `format: "text"` → a single synthesized `{ role: "user", content }`.
+ * Project a server `rendered` payload into the enriched result's `messages`.
+ *
+ * Prompts resolve as chat blocks. The deprecated `text` format is no longer a
+ * first-class case: a non-chat payload throws rather than being silently
+ * coerced (a text prompt is sugar for a single-block chat and is being removed
+ * from the API).
  */
-function renderedToMessages(rendered: RenderedPrompt): RenderedChatMessage[] {
-	if (rendered.format === "chat") {
-		return rendered.messages;
+function renderedToMessages(
+	rendered: ResolvedPrompt["rendered"],
+): RenderedChatMessage[] {
+	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;
 }
 
 /**
- * Normalize the server resolve envelope into the enriched R5 `FetchedPrompt`.
+ * Normalize the server resolve envelope into the enriched `RenderedPrompt`.
  *
- * - `messages` is synthesized from `rendered` via the D5 projection.
+ * - `messages` is derived from the `rendered` chat payload.
  * - `releaseId` is ALWAYS a key: a string when the server sends one, else
  *   explicit `null` (R5 `string | null`).
  * - `variantName` is present IFF the server sent one (i.e. weighted release);
@@ -177,9 +166,10 @@ function renderedToMessages(rendered: RenderedPrompt): RenderedChatMessage[] {
  */
 function normalizeResolvedEnvelope(
 	raw: ResolvedPrompt | ResolvedPromptEnvelope,
-): FetchedPrompt {
+	slug: string,
+): RenderedPrompt {
 	const provenance = raw as ResolvedPromptEnvelope;
-	const result: FetchedPrompt = {
+	const result: RenderedPrompt = {
 		messages: renderedToMessages(raw.rendered),
 		version: raw.version,
 		releaseId: provenance.releaseId ?? null,
@@ -188,7 +178,10 @@ function normalizeResolvedEnvelope(
 		versionId: raw.versionId,
 		contentHash: raw.contentHash,
 		label: raw.label,
-		rendered: raw.rendered,
+		// The requested slug — the API resolve envelope does not echo it, so it
+		// is threaded from the `render()` input (TO11-2727). Surfaced as
+		// `x-to11-prompt-slug` for trace readability.
+		slug,
 		modelConfig: provenance.modelConfig,
 	};
 	// `tools` is present IFF the resolved version declares tool definitions; the
@@ -219,20 +212,26 @@ function normalizeResolvedEnvelope(
 }
 
 /**
- * Lift a caller-supplied offline `fallback` into the enriched `FetchedPrompt`
- * shape (D7), so `render()` returns an identical shape on the online and
- * offline paths. An already-enriched `FetchedPrompt` is returned as-is; a
- * legacy `ResolvedPrompt` is lifted (messages synthesized; `releaseId` → its
- * own value or explicit `null`; `blockRenderRecord` → `{}`; `variantName`
- * stays absent).
+ * Lift a caller-supplied offline `fallback` into the returned shape (D7), so
+ * `render()` returns an identical shape on the online and offline paths. The
+ * fallback's own slug is preferred, falling back to the `render()` input when it
+ * carries none, so `x-to11-prompt-slug` is still emitted.
  */
-function liftFallbackToFetched(
-	fallback: ResolvedPrompt | FetchedPrompt,
-): FetchedPrompt {
-	if ("messages" in fallback) {
-		return structuredClone(fallback);
+function liftFallbackToRendered(
+	fallback: RenderedPrompt,
+	slug: string,
+): RenderedPrompt {
+	// Defensive: `fallback` is typed `RenderedPrompt`, but an untyped JS caller,
+	// an `as` cast, or a persisted pre-2.0 `resolve()` result could pass the old
+	// `ResolvedPrompt` shape (no top-level `messages`). Fail loudly rather than
+	// return a malformed result with `undefined` messages.
+	if (!Array.isArray((fallback as { messages?: unknown }).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);
+	// `||` (not `??`) so an empty-string slug also falls through to the input.
+	return { ...structuredClone(fallback), slug: fallback.slug || slug };
 }
 
 function getProjectPromptPath(projectId: string, promptId: string): string {
@@ -468,8 +467,7 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 	 * `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()`}.
+	 * `RenderedPrompt`. Resolves by the client's configured `env`.
 	 *
 	 * @example Render an OpenAI-shaped prompt and send it through the gateway
 	 * const prompt = await to11.prompts.render("weather-concierge", {
@@ -492,15 +490,15 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 	async render(
 		slug: string,
 		options: RenderOptions = {},
-	): Promise<FetchedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt> {
-		const fetched = await this.resolveToFetched(slug, options);
-		return shapePrompt(fetched, options.format ?? this.format, {
+	): Promise<RenderedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt> {
+		const rendered = await this.resolveToRendered(slug, options);
+		return shapePrompt(rendered, options.format ?? this.format, {
 			onUnknownRole: options.onUnknownRole ?? this.onUnknownRole,
 		});
 	}
 
 	/**
-	 * Env-aware resolution → neutral `FetchedPrompt`. Carries the resolve /
+	 * Env-aware resolution → neutral `RenderedPrompt`. Carries the resolve /
 	 * cache / offline-fallback logic; `render()` is the public shaping surface.
 	 *
 	 * - **env→label wire mapping:** the resolve route is label-based
@@ -513,10 +511,10 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 	 *   WITH a `subject`; BYPASSES the cache for weighted releases with NO
 	 *   `subject` (a uniform-random assignment must not be pinned for the TTL).
 	 */
-	private async resolveToFetched(
+	private async resolveToRendered(
 		slug: string,
-		options: FetchPromptOptions = {},
-	): Promise<FetchedPrompt> {
+		options: RenderOptions = {},
+	): Promise<RenderedPrompt> {
 		if (this.projectId === undefined || this.projectId.trim() === "") {
 			throw new Error(
 				"[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).",
@@ -543,7 +541,7 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 
 		const { subject, variables, cache: useCache = true, fallback } = options;
 
-		const cacheKey = buildFetchCacheKey(
+		const cacheKey = buildRenderCacheKey(
 			this.projectId,
 			slug,
 			env,
@@ -553,9 +551,7 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 
 		if (useCache) {
 			const cached = this.cache.get(cacheKey);
-			// Only enriched (fetch) entries are valid hits here; the fetch key
-			// namespace ("fetch|…") never collides with the legacy resolve key.
-			if (cached && "messages" in cached) return structuredClone(cached);
+			if (cached) return structuredClone(cached);
 		}
 
 		// env→label mapping: the env slug is the single resolution label.
@@ -574,7 +570,7 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 				},
 			);
 			const raw = unwrap(envelope);
-			const result = normalizeResolvedEnvelope(raw);
+			const result = normalizeResolvedEnvelope(raw, slug);
 
 			// D8: bypass the cache for a weighted release with NO subject —
 			// caching a uniform-random assignment would pin one variant for the
@@ -599,64 +595,7 @@ export class PromptResource<F extends RenderFormat | undefined = undefined> {
 			// client-eager throw already happened above the try, so there is no
 			// network error to trigger it on the env-missing path.
 			if (err instanceof To11aiNetworkError && fallback !== undefined) {
-				return liftFallbackToFetched(fallback);
-			}
-			throw err;
-		}
-	}
-
-	// ─── Resolve ──────────────────────────────────────────────────────────────
-
-	/**
-	 * 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.
-	 */
-	async resolve(input: ResolvePromptInput): Promise<ResolvePromptResult> {
-		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);
-			// The legacy resolve key namespace only ever stores ResolvedPrompt
-			// entries (the fetch namespace is "fetch|…"); the `messages` guard
-			// keeps the static return type as ResolvedPrompt.
-			if (cached && !("messages" in cached)) return structuredClone(cached);
-		}
-
-		try {
-			const envelope = await this.transport.request<ResolvePromptResult>(
-				"POST",
-				`${getProjectPromptsPath(projectId)}:resolve`,
-				{
-					body: { slug, labels, variables },
-					decode: (data) =>
-						zResolvedPromptLegacy.parse(data) as ResolvePromptResult,
-				},
-			);
-			const result = unwrap(envelope);
-
-			if (useCache) {
-				this.cache.set(cacheKey, structuredClone(result));
-			}
-
-			return result;
-		} catch (err) {
-			// If network error and we have a fallback, serve it
-			if (err instanceof To11aiNetworkError && fallback !== undefined) {
-				return fallback;
+				return liftFallbackToRendered(fallback, slug);
 			}
 			throw err;
 		}

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";
 
@@ -177,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;
@@ -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;
 	/**