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

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)}`;
@@ -109,13 +98,22 @@ class PromptResource {
     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
@@ -132,52 +130,60 @@ 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 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 +195,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 +212,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,61 +221,33 @@ 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;
     }
   }
-  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;
@@ -281,15 +259,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

@@ -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";
 /**
@@ -51,7 +50,7 @@ export interface PaginatedResult<T> {
     pagination: PaginationInfo;
 }
 export interface CreatePromptInput {
-    projectId: string;
+    projectId?: string;
     name: string;
     slug: string;
     description?: string;
@@ -59,7 +58,7 @@ export interface CreatePromptInput {
 }
 export type CreatePromptResult = Prompt;
 export interface ListPromptsInput {
-    projectId: string;
+    projectId?: string;
     status?: PromptStatus;
     sortBy?: "createdAt" | "updatedAt" | "name";
     tags?: string;
@@ -68,12 +67,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;
@@ -81,12 +80,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;
@@ -96,18 +95,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;
@@ -115,24 +114,13 @@ export interface MovePromptLabelInput {
 }
 export type MovePromptLabelResult = PromptLabelPointer;
 export interface ListPromptLabelsInput {
-    projectId: string;
+    projectId?: string;
     promptId: string;
 }
 export type ListPromptLabelsResult = PromptLabelPointer[];
-export interface ResolvePromptInput {
-    projectId: string;
-    slug: string;
-    labels: string[];
-    variables?: Record<string, unknown>;
-    /** Set false to bypass the LRU cache for this call. Default: true */
-    cache?: boolean;
-    /** Fallback prompt served if the API is unreachable and cache is empty. */
-    fallback?: ResolvedPrompt;
-}
-export type ResolvePromptResult = ResolvedPrompt;
 export 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;
     /**
@@ -197,13 +192,13 @@ 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;
@@ -211,12 +206,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;
@@ -224,18 +219,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;
@@ -244,7 +239,7 @@ export type ListLabelEventsInput = {
     until?: string;
 } | {
     scope: "prompt";
-    projectId: string;
+    projectId?: string;
     promptId: string;
     label?: string;
     page?: number;
@@ -253,7 +248,7 @@ export type ListLabelEventsInput = {
     until?: string;
 } | {
     scope: "project";
-    projectId: string;
+    projectId?: string;
     promptId?: string;
     label?: string;
     page?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@to11ai/sdk",
-	"version": "2.0.0-rc.1",
+	"version": "2.0.0-rc.3",
 	"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;
 	/**
@@ -246,6 +245,12 @@ export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
 	readonly apiKey: string | undefined;
 	/** Resolved data-plane gateway URL (option → `TO11_GATEWAY_URL` → default). */
 	readonly gatewayUrl: string;
+	/**
+	 * Resolved project id (option → `TO11_PROJECT_ID`); `undefined` when none is
+	 * configured. Read-only, for your own logging / manual headers — `prompts.*`
+	 * already default to it, so you don't need to pass it back into calls.
+	 */
+	readonly projectId: string | undefined;
 	/** A new session (unit of work). Pass an id to group telemetry by your own id. */
 	session(id?: string): Session;
 	/**
@@ -376,7 +381,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 +408,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.
@@ -520,6 +535,7 @@ export function createClient<
 			behaviorStore.resolve(key, codedDefault),
 		apiKey,
 		gatewayUrl,
+		projectId,
 		session: (id) => new Session(gatewayAuthContext(), id),
 		conversation: (id) => clientDefaultSession().conversation(id),
 		turn: () => clientDefaultSession().turn(),

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;
 }