@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/dist/errors.cjs

@@ -39,6 +39,7 @@ var __export = (target, all) => {
 // src/errors.ts
 var exports_errors = {};
 __export(exports_errors, {
+  UnknownRoleError: () => UnknownRoleError,
   To11aiValidationError: () => To11aiValidationError,
   To11aiResponseValidationError: () => To11aiResponseValidationError,
   To11aiRateLimitError: () => To11aiRateLimitError,
@@ -53,9 +54,9 @@ __export(exports_errors, {
   PromptLabelNotRegisteredError: () => PromptLabelNotRegisteredError,
   NoApplicableRouteError: () => NoApplicableRouteError,
   NoActiveReleaseError: () => NoActiveReleaseError,
-  EnvNotFoundError: () => EnvNotFoundError,
-  EnvNotEnabledForProviderError: () => EnvNotEnabledForProviderError,
-  AmbiguousEnvLabelsError: () => AmbiguousEnvLabelsError
+  MissingLabelError: () => MissingLabelError,
+  LabelNotFoundError: () => LabelNotFoundError,
+  EnvNotEnabledForProviderError: () => EnvNotEnabledForProviderError
 });
 module.exports = __toCommonJS(exports_errors);
 
@@ -130,6 +131,22 @@ class To11aiResponseValidationError extends To11aiError {
   }
 }
 
+class UnknownRoleError extends To11aiError {
+  code = "unknown_role";
+  role;
+  index;
+  constructor(role, index) {
+    super(`[to11ai/sdk] message[${index}] has unknown role ${JSON.stringify(role)}; expected system|user|assistant|developer|tool`);
+    this.name = "UnknownRoleError";
+    this.role = role;
+    this.index = index;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static is(err) {
+    return err instanceof UnknownRoleError;
+  }
+}
+
 class PromptLabelNotRegisteredError extends To11aiApiError {
   projectId;
   label;
@@ -209,19 +226,27 @@ class PromptNotFoundError extends To11aiApiError {
   }
 }
 
-class EnvNotFoundError extends To11aiApiError {
-  reason;
-  constructor(message, reason, details, statusCode) {
+class LabelNotFoundError extends To11aiApiError {
+  label;
+  constructor(message, label, details, statusCode) {
     super(message, statusCode, "ENV_NOT_FOUND", details);
-    this.name = "EnvNotFoundError";
-    this.reason = reason;
+    this.name = "LabelNotFoundError";
+    this.label = label;
     Object.setPrototypeOf(this, new.target.prototype);
   }
-  static missing(env) {
-    return new EnvNotFoundError("[to11ai/sdk] No environment resolvable for prompts.fetch(): none supplied at client init and none supplied per call. Pass `env` to createClient or fetch(slug, { env }).", { env, source: "missing" }, undefined, 0);
+  static is(err) {
+    return err instanceof LabelNotFoundError;
+  }
+}
+
+class MissingLabelError extends To11aiError {
+  constructor(message = "[to11ai/sdk] No label resolvable for prompts.render(): none supplied per call, and no client env (or TO11_ENV) to fall back to. Pass `label` to render(slug, { label }) or set `env` on createClient.") {
+    super(message);
+    this.name = "MissingLabelError";
+    Object.setPrototypeOf(this, new.target.prototype);
   }
   static is(err) {
-    return err instanceof EnvNotFoundError;
+    return err instanceof MissingLabelError;
   }
 }
 
@@ -251,19 +276,6 @@ class PromptPolicyViolationError extends To11aiApiError {
   }
 }
 
-class AmbiguousEnvLabelsError extends To11aiApiError {
-  reason;
-  constructor(message, reason, details, statusCode = 409) {
-    super(message, statusCode, "AMBIGUOUS_ENV_LABELS", details);
-    this.name = "AmbiguousEnvLabelsError";
-    this.reason = reason;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-  static is(err) {
-    return err instanceof AmbiguousEnvLabelsError;
-  }
-}
-
 class RuleVersionInvalidSnapshotError extends To11aiApiError {
   field;
   reason;

package/dist/errors.d.ts

@@ -51,6 +51,23 @@ export declare class To11aiResponseValidationError extends To11aiError {
     }[];
     constructor(path: string, zodError: unknown, cause?: unknown);
 }
+/**
+ * Thrown by the provider-shape converters (`toOpenAIMessages` /
+ * `toAnthropicMessages`, and `render({ format })`) in `onUnknownRole: "error"`
+ * mode when a message carries a role outside the known set
+ * (`system | user | assistant | developer | tool`). `code` is the stable
+ * `"unknown_role"` slug; `role` / `index` locate the offending turn.
+ *
+ * A client-side conversion error — it extends `To11aiError` (not
+ * `To11aiApiError`), so it never carries an HTTP status.
+ */
+export declare class UnknownRoleError extends To11aiError {
+    readonly code = "unknown_role";
+    readonly role: string;
+    readonly index: number;
+    constructor(role: string, index: number);
+    static is(err: unknown): err is UnknownRoleError;
+}
 /**
  * Thrown when strict-mode rejects a label move for an unregistered label.
  *
@@ -154,35 +171,29 @@ export declare class PromptNotFoundError extends To11aiApiError {
     static is(err: unknown): err is PromptNotFoundError;
 }
 /**
- * Reason payload for `EnvNotFoundError`.
+ * Thrown when the label supplied to `prompts.render()` does not resolve to an
+ * existing (active) label on the server. Surfaced from the server's
+ * `ENV_NOT_FOUND` code; `label` carries the rejected slug when the server
+ * echoes it.
  *
- * `source` discriminates the two failure modes (D2):
- *   - `"missing"` — no env was supplied at init OR at call time. Raised
- *     CLIENT-side, eagerly, before any request (R4 / AC4); `env` is absent.
- *   - `"unknown"` — an env was supplied but the server's registry has no
- *     such (active) env. Surfaced from the `ENV_NOT_FOUND` server code; `env`
- *     carries the rejected slug when the server echoes it.
+ * This is distinct from `MissingLabelError`, which is raised client-side when
+ * no label was supplied at all.
  */
-export interface EnvNotFoundReason {
-    env?: string;
-    source: "missing" | "unknown";
+export declare class LabelNotFoundError extends To11aiApiError {
+    /** The label slug that could not be found, when the server echoes it. */
+    readonly label?: string;
+    constructor(message: string, label: string | undefined, details: unknown, statusCode: number);
+    static is(err: unknown): err is LabelNotFoundError;
 }
 /**
- * Thrown when no serving environment can be resolved for a `prompts.fetch()`
- * call. One class, two `reason.source` discriminants (see
- * `EnvNotFoundReason`): client-eager `"missing"` (R4) and server-forwarded
- * `"unknown"` (`ENV_NOT_FOUND`).
- *
- * The client-eager variant carries no `statusCode`/`errorCode` from the wire
- * (no request was made); it reports status `0` and errorCode `ENV_NOT_FOUND`
- * for a uniform catch surface.
+ * Thrown CLIENT-side, eagerly (before any request), when `prompts.render()` is
+ * called but no label is resolvable at all: none supplied per call, and no
+ * client `env` (or `TO11_ENV`) to fall back to. A usage error, not a lookup
+ * failure — distinct from `LabelNotFoundError`.
  */
-export declare class EnvNotFoundError extends To11aiApiError {
-    readonly reason: EnvNotFoundReason;
-    constructor(message: string, reason: EnvNotFoundReason, details: unknown, statusCode: number);
-    /** Build the client-eager (missing-at-both) variant — no transport call. */
-    static missing(env?: string): EnvNotFoundError;
-    static is(err: unknown): err is EnvNotFoundError;
+export declare class MissingLabelError extends To11aiError {
+    constructor(message?: string);
+    static is(err: unknown): err is MissingLabelError;
 }
 /**
  * Reason payload for `NoActiveReleaseError`.
@@ -233,28 +244,6 @@ export declare class PromptPolicyViolationError extends To11aiApiError {
     constructor(message: string, reason: PromptPolicyViolationReason, details?: unknown, statusCode?: number);
     static is(err: unknown): err is PromptPolicyViolationError;
 }
-/**
- * Reason payload for `AmbiguousEnvLabelsError`.
- *
- * Carried when the supplied env-label matched more than one candidate
- * version and the server cannot pick deterministically
- * (`AMBIGUOUS_ENV_LABELS`).
- */
-export interface AmbiguousEnvLabelsReason {
-    env?: string;
-    slug?: string;
-}
-/**
- * Thrown when the env→label resolution is ambiguous on the server
- * (`AMBIGUOUS_ENV_LABELS`) — the label matched multiple candidates and the
- * server declines to guess. Surfaces (rather than 500ing) so callers get a
- * typed, actionable error.
- */
-export declare class AmbiguousEnvLabelsError extends To11aiApiError {
-    readonly reason: AmbiguousEnvLabelsReason;
-    constructor(message: string, reason: AmbiguousEnvLabelsReason, details?: unknown, statusCode?: number);
-    static is(err: unknown): err is AmbiguousEnvLabelsError;
-}
 /**
  * Thrown when version create rejects the snapshot for a structural
  * reason — invalid variant params, malformed `when` clause, illegal

package/dist/errors.js

@@ -70,6 +70,22 @@ class To11aiResponseValidationError extends To11aiError {
   }
 }
 
+class UnknownRoleError extends To11aiError {
+  code = "unknown_role";
+  role;
+  index;
+  constructor(role, index) {
+    super(`[to11ai/sdk] message[${index}] has unknown role ${JSON.stringify(role)}; expected system|user|assistant|developer|tool`);
+    this.name = "UnknownRoleError";
+    this.role = role;
+    this.index = index;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static is(err) {
+    return err instanceof UnknownRoleError;
+  }
+}
+
 class PromptLabelNotRegisteredError extends To11aiApiError {
   projectId;
   label;
@@ -149,19 +165,27 @@ class PromptNotFoundError extends To11aiApiError {
   }
 }
 
-class EnvNotFoundError extends To11aiApiError {
-  reason;
-  constructor(message, reason, details, statusCode) {
+class LabelNotFoundError extends To11aiApiError {
+  label;
+  constructor(message, label, details, statusCode) {
     super(message, statusCode, "ENV_NOT_FOUND", details);
-    this.name = "EnvNotFoundError";
-    this.reason = reason;
+    this.name = "LabelNotFoundError";
+    this.label = label;
     Object.setPrototypeOf(this, new.target.prototype);
   }
-  static missing(env) {
-    return new EnvNotFoundError("[to11ai/sdk] No environment resolvable for prompts.fetch(): none supplied at client init and none supplied per call. Pass `env` to createClient or fetch(slug, { env }).", { env, source: "missing" }, undefined, 0);
+  static is(err) {
+    return err instanceof LabelNotFoundError;
+  }
+}
+
+class MissingLabelError extends To11aiError {
+  constructor(message = "[to11ai/sdk] No label resolvable for prompts.render(): none supplied per call, and no client env (or TO11_ENV) to fall back to. Pass `label` to render(slug, { label }) or set `env` on createClient.") {
+    super(message);
+    this.name = "MissingLabelError";
+    Object.setPrototypeOf(this, new.target.prototype);
   }
   static is(err) {
-    return err instanceof EnvNotFoundError;
+    return err instanceof MissingLabelError;
   }
 }
 
@@ -191,19 +215,6 @@ class PromptPolicyViolationError extends To11aiApiError {
   }
 }
 
-class AmbiguousEnvLabelsError extends To11aiApiError {
-  reason;
-  constructor(message, reason, details, statusCode = 409) {
-    super(message, statusCode, "AMBIGUOUS_ENV_LABELS", details);
-    this.name = "AmbiguousEnvLabelsError";
-    this.reason = reason;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-  static is(err) {
-    return err instanceof AmbiguousEnvLabelsError;
-  }
-}
-
 class RuleVersionInvalidSnapshotError extends To11aiApiError {
   field;
   reason;
@@ -221,6 +232,7 @@ class RuleVersionInvalidSnapshotError extends To11aiApiError {
   }
 }
 export {
+  UnknownRoleError,
   To11aiValidationError,
   To11aiResponseValidationError,
   To11aiRateLimitError,
@@ -235,7 +247,7 @@ export {
   PromptLabelNotRegisteredError,
   NoApplicableRouteError,
   NoActiveReleaseError,
-  EnvNotFoundError,
-  EnvNotEnabledForProviderError,
-  AmbiguousEnvLabelsError
+  MissingLabelError,
+  LabelNotFoundError,
+  EnvNotEnabledForProviderError
 };

package/dist/gateway.cjs

@@ -44,11 +44,13 @@ __export(exports_gateway, {
   toOpenAIMessages: () => toOpenAIMessages,
   toAnthropicTools: () => toAnthropicTools,
   toAnthropicToolChoice: () => toAnthropicToolChoice,
+  toAnthropicSystem: () => toAnthropicSystem,
   toAnthropicMessages: () => toAnthropicMessages,
   gatewayPromptHeaders: () => gatewayPromptHeaders,
   gatewayAuthHeaders: () => gatewayAuthHeaders
 });
 module.exports = __toCommonJS(exports_gateway);
+var import_errors = require("./errors");
 var import_types = require("./prompts/types");
 function gatewayAuthHeaders(options) {
   if (options.apiKey.trim().length === 0) {
@@ -73,20 +75,27 @@ function gatewayAuthHeaders(options) {
   return headers;
 }
 function gatewayPromptHeaders(prompt) {
-  const headers = {
-    "x-to11-prompt-id": prompt.promptId,
-    "x-to11-prompt-version": String(prompt.version)
-  };
-  const releaseId = prompt.releaseId;
-  if (typeof releaseId === "string" && releaseId.length > 0) {
-    headers["x-to11-release-id"] = releaseId;
+  const p = prompt != null && "metadata" in prompt ? prompt.metadata : prompt;
+  const headers = {};
+  if (p == null)
+    return headers;
+  if (typeof p.promptId === "string" && p.promptId.length > 0) {
+    headers["x-to11-prompt-id"] = p.promptId;
+  }
+  if (typeof p.version === "number" && Number.isFinite(p.version)) {
+    headers["x-to11-prompt-version"] = String(p.version);
+  }
+  if (typeof p.releaseId === "string" && p.releaseId.length > 0) {
+    headers["x-to11-release-id"] = p.releaseId;
   }
-  const variantName = prompt.variantName;
-  if (typeof variantName === "string" && variantName.length > 0) {
-    headers["x-to11-variant-name"] = variantName;
+  if (typeof p.variantName === "string" && p.variantName.length > 0) {
+    headers["x-to11-variant-name"] = p.variantName;
   }
-  if (prompt.labels.length > 0) {
-    headers["x-to11-prompt-labels"] = prompt.labels.join(",");
+  if (typeof p.label === "string" && p.label.length > 0) {
+    headers["x-to11-prompt-label"] = p.label;
+  }
+  if (typeof p.slug === "string" && p.slug.length > 0) {
+    headers["x-to11-prompt-slug"] = p.slug;
   }
   return headers;
 }
@@ -142,41 +151,73 @@ function requireToolCallId(id) {
   }
   return id;
 }
-function toOpenAIMessages(messages) {
-  return messages.map((message) => {
+var KNOWN_RENDERED_ROLES = new Set([
+  "system",
+  "user",
+  "assistant",
+  "developer",
+  "tool"
+]);
+function skipUnknownRole(role, index, mode) {
+  if (KNOWN_RENDERED_ROLES.has(role))
+    return false;
+  if (mode === "error")
+    throw new import_errors.UnknownRoleError(role, index);
+  if (mode === "warn") {
+    console.warn(`[to11ai/sdk] dropped message[${index}] with unknown role ${JSON.stringify(role)} (expected system|user|assistant|developer|tool)`);
+  }
+  return true;
+}
+function toOpenAIMessages(messages, options = {}) {
+  const mode = options.onUnknownRole ?? "drop";
+  const out = [];
+  messages.forEach((message, index) => {
+    if (skipUnknownRole(message.role, index, mode))
+      return;
     if (message.role === "tool") {
-      return {
+      out.push({
         role: "tool",
         tool_call_id: requireToolCallId(message.toolCallId),
         content: message.content ?? ""
-      };
+      });
+      return;
     }
     if (message.role === "assistant") {
-      const out = {
+      const content2 = message.content ?? null;
+      out.push(message.toolCalls != null && message.toolCalls.length > 0 ? {
         role: "assistant",
-        content: message.content ?? null
-      };
-      if (message.toolCalls != null && message.toolCalls.length > 0) {
-        out.tool_calls = message.toolCalls.map((call) => ({
+        content: content2,
+        tool_calls: message.toolCalls.map((call) => ({
           id: requireToolCallId(call.id),
           type: "function",
           function: {
             name: call.name,
             arguments: JSON.stringify(call.arguments)
           }
-        }));
-      }
-      return out;
+        }))
+      } : { role: "assistant", content: content2 });
+      return;
+    }
+    const content = message.content ?? "";
+    if (message.role === "user") {
+      out.push({ role: "user", content });
+    } else if (message.role === "developer") {
+      out.push({ role: "developer", content });
+    } else {
+      out.push({ role: "system", content });
     }
-    return { role: message.role, content: message.content ?? "" };
   });
+  return out;
 }
-function toAnthropicMessages(messages) {
+function toAnthropicMessages(messages, options = {}) {
+  const mode = options.onUnknownRole ?? "drop";
   const out = [];
-  for (const message of messages) {
+  messages.forEach((message, index) => {
     if (message.role === "system" || message.role === "developer") {
-      continue;
+      return;
     }
+    if (skipUnknownRole(message.role, index, mode))
+      return;
     if (message.role === "tool") {
       out.push({
         role: "user",
@@ -188,7 +229,7 @@ function toAnthropicMessages(messages) {
           }
         ]
       });
-      continue;
+      return;
     }
     if (message.role === "assistant") {
       if (message.toolCalls != null && message.toolCalls.length > 0) {
@@ -208,9 +249,22 @@ function toAnthropicMessages(messages) {
       } else {
         out.push({ role: "assistant", content: message.content ?? "" });
       }
-      continue;
+      return;
     }
     out.push({ role: "user", content: message.content ?? "" });
-  }
+  });
   return out;
 }
+function toAnthropicSystem(messages) {
+  const parts = [];
+  for (const message of messages) {
+    if (message.role !== "system" && message.role !== "developer")
+      continue;
+    if (typeof message.content === "string" && message.content.length > 0) {
+      parts.push(message.content);
+    }
+  }
+  return parts.length > 0 ? parts.join(`
+
+`) : undefined;
+}

package/dist/gateway.d.ts

@@ -1,4 +1,4 @@
-import { type FetchedPrompt, type RenderedChatMessage, type ResolvedPrompt, type ResolvedToolDefinition } from "./prompts/types";
+import { type RenderedChatMessage, type ResolvedPrompt, type ResolvedToolDefinition, type UnknownRoleMode } from "./prompts/types";
 export interface GatewayAuthOptions {
     apiKey: string;
     projectId: string;
@@ -30,29 +30,46 @@ export interface GatewayAuthOptions {
  */
 export declare function gatewayAuthHeaders(options: GatewayAuthOptions): Record<string, string>;
 /**
- * Build prompt provenance headers from a resolved prompt (TO11-980 / R7).
- *
- * Emits the full provenance set for every gateway-bound LLM request that
- * follows from a resolved prompt:
- *   - `x-to11-prompt-id`, `x-to11-prompt-version` — always.
- *   - `x-to11-release-id` — when the result carries a non-null `releaseId`
- *     (the enriched `fetch()` result; a legacy `resolve()` result has no
- *     `releaseId`, so it is omitted — non-breaking).
- *   - `x-to11-variant-name` — IFF `variantName` is present (i.e. the resolved
- *     release was weighted); omitted for `single`-strategy releases.
- *   - `x-to11-prompt-labels` — omitted when empty (the gateway rejects empty
- *     header values); behavior unchanged.
- *
- * The parameter type is WIDENED to accept either the enriched `fetch()`
- * result or the legacy `ResolvedPrompt`. The new fields are read when present
- * and omitted otherwise, so an old `resolve()` result still produces exactly
- * the original three headers (non-breaking; D1/D7 shape coexistence).
+ * Build prompt provenance headers from a `render()` result (or a format-shaped
+ * result's `metadata`, unwrapped automatically).
+ *
+ * No provenance header is required, and the gateway rejects empty header
+ * values — so each header is emitted only when its value is present and valid,
+ * and the function never throws:
+ *   - `x-to11-prompt-id` — a non-empty string.
+ *   - `x-to11-prompt-version` — a finite number (a non-number/NaN is dropped
+ *     rather than stringified to junk like `"[object Object]"`).
+ *   - `x-to11-release-id` — a non-empty `releaseId` (the offline-fallback path
+ *     can carry an explicit `null`, which is omitted).
+ *   - `x-to11-variant-name` — present IFF the resolved release was weighted.
+ *   - `x-to11-prompt-label` — the single label the prompt resolved through.
+ *   - `x-to11-prompt-slug` — the prompt's human-readable slug.
+ *
+ * An input with no usable provenance yields an empty header bag — the same as
+ * a prompt-less `turn.headers()` call.
  *
  * @example
- * const result = await client.prompts.fetch(slug, { env: "prod" });
+ * const result = await client.prompts.render(slug, { label: "prod" });
  * const headers = gatewayPromptHeaders(result);
  */
-export declare function gatewayPromptHeaders(prompt: ResolvedPrompt | FetchedPrompt): Record<string, string>;
+export interface GatewayPromptProvenance {
+    promptId: string;
+    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. */
+    variantName?: string;
+}
+export declare function gatewayPromptHeaders(prompt: GatewayPromptProvenance | {
+    metadata: GatewayPromptProvenance;
+}): Record<string, string>;
 /** OpenAI Chat Completions `tools[]` entry (`function` tool). */
 export interface OpenAITool {
     type: "function";
@@ -78,13 +95,33 @@ export interface OpenAIToolCall {
         arguments: string;
     };
 }
-/** OpenAI Chat Completions `messages[]` entry. */
-export interface OpenAIChatMessage {
-    role: "system" | "developer" | "user" | "assistant" | "tool";
+/**
+ * OpenAI Chat Completions `messages[]` entry — a per-role discriminated union
+ * matching what Chat Completions requires for each role, so an
+ * `OpenAIChatMessage[]` is structurally assignable to the `openai` package's
+ * `ChatCompletionMessageParam[]` (a `render({ format: "openai" })` result spreads
+ * straight into `openai.chat.completions.create({ messages })` with no cast).
+ * The SDK carries no dependency on the `openai` package — this only mirrors its
+ * shape. (Assignability is regression-guarded in `gateway.provider-types.test.ts`.)
+ */
+export type OpenAIChatMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "developer";
+    content: string;
+} | {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
     content?: string | null;
     tool_calls?: OpenAIToolCall[];
-    tool_call_id?: string;
-}
+} | {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+};
 /** Anthropic Messages `tools[]` entry. */
 export interface AnthropicTool {
     name: string;
@@ -175,6 +212,16 @@ export declare function toAnthropicTools(tools: ReadonlyArray<ResolvedToolDefini
  * await anthropic.messages.create({ model, system, messages, tools, tool_choice });
  */
 export declare function toAnthropicToolChoice(toolChoice: ResolvedPrompt["toolChoice"]): AnthropicToolChoice | undefined;
+/** Options shared by the message converters. */
+export interface ConvertMessagesOptions {
+    /**
+     * Policy for a message whose role is outside the known set
+     * (`system | user | assistant | developer | tool`). `"drop"` (default) omits
+     * it silently; `"warn"` omits it and emits a `console.warn`; `"error"` throws
+     * {@link UnknownRoleError}. Both converters apply this identically.
+     */
+    onUnknownRole?: UnknownRoleMode;
+}
 /**
  * Shape rendered turns for the OpenAI Chat Completions `messages` field.
  *
@@ -184,11 +231,15 @@ export declare function toAnthropicToolChoice(toolChoice: ResolvedPrompt["toolCh
  *   become `tool_calls[]` with JSON-stringified `arguments` (the OpenAI wire
  *   shape). A pure tool-call turn keeps `content: null`.
  * - `tool` (result) → `{ role: "tool", tool_call_id, content }`.
+ * - an unrecognized role is handled per `options.onUnknownRole` (default
+ *   `"drop"`) — dropped, dropped-with-warning, or throws `UnknownRoleError`.
  *
  * @example
  * const messages = toOpenAIMessages(prompt.messages);
+ * @example Fail loudly on a malformed message array
+ * const messages = toOpenAIMessages(history, { onUnknownRole: "error" });
  */
-export declare function toOpenAIMessages(messages: ReadonlyArray<RenderedChatMessage>): OpenAIChatMessage[];
+export declare function toOpenAIMessages(messages: ReadonlyArray<RenderedChatMessage>, options?: ConvertMessagesOptions): OpenAIChatMessage[];
 /**
  * Shape rendered turns for the Anthropic Messages `messages` field.
  *
@@ -201,8 +252,32 @@ export declare function toOpenAIMessages(messages: ReadonlyArray<RenderedChatMes
  *   ...tool_use] }`; without calls → `{ role: "assistant", content }`.
  * - `tool` (result) → `{ role: "user", content: [{ type: "tool_result",
  *   tool_use_id, content }] }`.
+ * - an unrecognized role is handled per `options.onUnknownRole` (default
+ *   `"drop"`) — dropped, dropped-with-warning, or throws `UnknownRoleError` —
+ *   identically to {@link toOpenAIMessages}. (`system`/`developer` are known
+ *   roles folded into `system`, not "unknown"; they are never dropped here.)
  *
  * @example
  * const messages = toAnthropicMessages(prompt.messages);
+ * @example Fail loudly on a malformed message array
+ * const messages = toAnthropicMessages(history, { onUnknownRole: "error" });
+ */
+export declare function toAnthropicMessages(messages: ReadonlyArray<RenderedChatMessage>, options?: ConvertMessagesOptions): AnthropicMessage[];
+/**
+ * Fold the `system` and `developer` instruction turns into Anthropic's
+ * top-level `system` string. Anthropic has no `developer` role and takes system
+ * instructions as a separate request field, so pair this with
+ * {@link toAnthropicMessages} (which omits those turns). Returns `undefined`
+ * when there is no system/developer content.
+ *
+ * @example
+ * const res = await anthropic.messages.create(
+ *   {
+ *     ...prompt.config,
+ *     system: toAnthropicSystem(prompt.messages),
+ *     messages: toAnthropicMessages(prompt.messages),
+ *   },
+ *   { headers: to11.turn().headers(prompt) },
+ * );
  */
-export declare function toAnthropicMessages(messages: ReadonlyArray<RenderedChatMessage>): AnthropicMessage[];
+export declare function toAnthropicSystem(messages: ReadonlyArray<RenderedChatMessage>): string | undefined;