@to11ai/sdk 1.0.0 → 2.0.0-rc.1

package/dist/context.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Observability context — the `session → conversation → turn` hierarchy that
+ * maps onto to11's telemetry grouping (Session → Conversation → Turn →
+ * LLM-Call). Each level provides a lazy default for the level below; explicit
+ * control is opt-in per use case. See
+ * docs/product-specs/2026-07-14-to11-2691-sdk-simpler-setup.md.
+ *
+ * Header-only: `turn.headers(prompt?)` returns a plain object the caller applies
+ * to their own provider client. It never sends a request.
+ */
+import { type GatewayPromptProvenance } from "./gateway";
+/** Auth/config the client hands to the context for gateway header building. */
+export interface TurnAuthContext {
+    readonly apiKey: string;
+    readonly projectId: string;
+    readonly env?: string;
+}
+/**
+ * A prompt argument accepted by `turn.headers()`. Either the flat provenance
+ * (a neutral `FetchedPrompt`) or a `format`-shaped result carrying it under
+ * `metadata` — both are accepted so the format and neutral render paths carry
+ * provenance identically.
+ */
+export type PromptForHeaders = GatewayPromptProvenance | {
+    metadata: GatewayPromptProvenance;
+};
+/**
+ * One agent turn — a single trace. A turn's `traceparent` is fixed for its
+ * lifetime, so every LLM-call made under it groups into one trace.
+ */
+export declare class Turn {
+    private readonly auth;
+    readonly sessionId: string;
+    readonly conversationId: string;
+    /** The fixed W3C traceparent for this turn (one trace). */
+    readonly traceparent: string;
+    constructor(auth: TurnAuthContext, sessionId: string, conversationId: string, traceparent?: string);
+    /**
+     * The complete gateway header bag: auth + session + conversation +
+     * traceparent, plus prompt provenance when a `prompt` is supplied. A pure
+     * read of the turn's fixed ids — reuse it across a tool-loop or call per
+     * request; the result is identical.
+     *
+     * Only valid for requests targeting the gateway (`GATEWAY_URL`); it carries
+     * the to11 API key and must never be attached to a direct provider endpoint.
+     *
+     * @example One call (inline turn)
+     * const res = await openai.chat.completions.create(
+     *   { ...prompt.config, messages: prompt.messages },
+     *   { headers: to11.turn().headers(prompt) },
+     * );
+     *
+     * @example Tool loop — hoist the turn so every call shares one trace
+     * const turn = to11.turn();
+     * const headers = turn.headers(prompt);
+     * while (true) {
+     *   const res = await openai.chat.completions.create({ ...prompt.config, messages, tools }, { headers });
+     *   // …reuse `headers` for every call in the loop…
+     * }
+     */
+    headers(prompt?: PromptForHeaders): Record<string, string>;
+}
+/** One agent thread — a stable conversation id shared across all its turns. */
+export declare class Conversation {
+    private readonly auth;
+    readonly sessionId: string;
+    /** Stable conversation id, reused by every turn created from this object. */
+    readonly id: string;
+    constructor(auth: TurnAuthContext, sessionId: string, id?: string);
+    /** Start a new turn (fresh trace) in this conversation. */
+    turn(): Turn;
+}
+/**
+ * One unit of work. Groups conversations under a single session id. A session
+ * lazily owns one default conversation, used by `session.turn()`; call
+ * `session.conversation()` for additional (side/parallel) agent threads.
+ */
+export declare class Session {
+    private readonly auth;
+    /** Stable session id, carried by every conversation and turn beneath it. */
+    readonly id: string;
+    private defaultConversation;
+    constructor(auth: TurnAuthContext, id?: string);
+    /**
+     * Create a distinct conversation (a separate agent thread) in this session.
+     * Use this when one unit of work runs multiple agents (side / parallel
+     * agents): each conversation gets its own `x-to11-conversation-id`, all under
+     * the one session.
+     *
+     * @example Multiple agents in one session
+     * const session  = to11.session();
+     * const main     = session.conversation();   // main agent thread
+     * const research = session.conversation();   // separate research thread, same session
+     *
+     * await openai.chat.completions.create(
+     *   { ...mainPrompt.config, messages: mainMessages },
+     *   { headers: main.turn().headers(mainPrompt) },
+     * );
+     * await openai.chat.completions.create(
+     *   { ...researchPrompt.config, messages: researchMessages },
+     *   { headers: research.turn().headers(researchPrompt) },
+     * );
+     */
+    conversation(id?: string): Conversation;
+    /**
+     * Start a turn in the session's single implicit conversation. The default
+     * conversation is created lazily on first call and reused, so consecutive
+     * `session.turn()` calls share one `x-to11-conversation-id` (each with its
+     * own `traceparent`).
+     *
+     * @example Multi-turn chat — every turn shares the session's conversation
+     * const session = to11.session();
+     * for await (const input of inputs) {
+     *   messages.push({ role: "user", content: input });
+     *   const turn = session.turn(); // fresh trace, same conversation id
+     *   const res = await openai.chat.completions.create(
+     *     { ...prompt.config, messages },
+     *     { headers: turn.headers(prompt) },
+     *   );
+     *   messages.push(res.choices[0].message);
+     * }
+     */
+    turn(): Turn;
+}

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,
@@ -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;
@@ -218,7 +235,7 @@ class EnvNotFoundError extends To11aiApiError {
     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);
+    return new EnvNotFoundError("[to11ai/sdk] No environment resolvable for prompts.render(): none supplied at client init and none supplied per call. Pass `env` to createClient or render(slug, { env }).", { env, source: "missing" }, undefined, 0);
   }
   static is(err) {
     return err instanceof EnvNotFoundError;

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.
  *
@@ -168,7 +185,7 @@ export interface EnvNotFoundReason {
     source: "missing" | "unknown";
 }
 /**
- * Thrown when no serving environment can be resolved for a `prompts.fetch()`
+ * Thrown when no serving environment can be resolved for a `prompts.render()`
  * call. One class, two `reason.source` discriminants (see
  * `EnvNotFoundReason`): client-eager `"missing"` (R4) and server-forwarded
  * `"unknown"` (`ENV_NOT_FOUND`).

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;
@@ -158,7 +174,7 @@ class EnvNotFoundError extends To11aiApiError {
     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);
+    return new EnvNotFoundError("[to11ai/sdk] No environment resolvable for prompts.render(): none supplied at client init and none supplied per call. Pass `env` to createClient or render(slug, { env }).", { env, source: "missing" }, undefined, 0);
   }
   static is(err) {
     return err instanceof EnvNotFoundError;
@@ -221,6 +237,7 @@ class RuleVersionInvalidSnapshotError extends To11aiApiError {
   }
 }
 export {
+  UnknownRoleError,
   To11aiValidationError,
   To11aiResponseValidationError,
   To11aiRateLimitError,

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) {
@@ -77,16 +79,14 @@ function gatewayPromptHeaders(prompt) {
     "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;
+  if (typeof prompt.releaseId === "string" && prompt.releaseId.length > 0) {
+    headers["x-to11-release-id"] = prompt.releaseId;
   }
-  const variantName = prompt.variantName;
-  if (typeof variantName === "string" && variantName.length > 0) {
-    headers["x-to11-variant-name"] = variantName;
+  if (typeof prompt.variantName === "string" && prompt.variantName.length > 0) {
+    headers["x-to11-variant-name"] = prompt.variantName;
   }
-  if (prompt.labels.length > 0) {
-    headers["x-to11-prompt-labels"] = prompt.labels.join(",");
+  if (prompt.label.length > 0) {
+    headers["x-to11-prompt-label"] = prompt.label;
   }
   return headers;
 }
@@ -142,22 +142,44 @@ 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 msg = {
         role: "assistant",
         content: message.content ?? null
       };
       if (message.toolCalls != null && message.toolCalls.length > 0) {
-        out.tool_calls = message.toolCalls.map((call) => ({
+        msg.tool_calls = message.toolCalls.map((call) => ({
           id: requireToolCallId(call.id),
           type: "function",
           function: {
@@ -166,17 +188,22 @@ function toOpenAIMessages(messages) {
           }
         }));
       }
-      return out;
+      out.push(msg);
+      return;
     }
-    return { role: message.role, content: message.content ?? "" };
+    out.push({ 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 +215,7 @@ function toAnthropicMessages(messages) {
           }
         ]
       });
-      continue;
+      return;
     }
     if (message.role === "assistant") {
       if (message.toolCalls != null && message.toolCalls.length > 0) {
@@ -208,9 +235,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;
@@ -36,23 +36,33 @@ export declare function gatewayAuthHeaders(options: GatewayAuthOptions): Record<
  * 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
+ *     (the enriched `render()` 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.
+ *   - `x-to11-prompt-label` — the single label the prompt resolved through (the
+ *     env slug today); omitted when empty (the gateway rejects empty values).
  *
- * The parameter type is WIDENED to accept either the enriched `fetch()`
+ * The parameter type is WIDENED to accept either the enriched `render()`
  * 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).
  *
  * @example
- * const result = await client.prompts.fetch(slug, { env: "prod" });
+ * const result = await client.prompts.render(slug, { env: "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;
+    /** 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): Record<string, string>;
 /** OpenAI Chat Completions `tools[]` entry (`function` tool). */
 export interface OpenAITool {
     type: "function";
@@ -175,6 +185,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 +204,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 +225,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;

package/dist/gateway.js

@@ -1,4 +1,5 @@
 // src/gateway.ts
+import { UnknownRoleError } from "./errors";
 import {
   ENV_SLUG_REGEX
 } from "./prompts/types";
@@ -29,16 +30,14 @@ function gatewayPromptHeaders(prompt) {
     "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;
+  if (typeof prompt.releaseId === "string" && prompt.releaseId.length > 0) {
+    headers["x-to11-release-id"] = prompt.releaseId;
   }
-  const variantName = prompt.variantName;
-  if (typeof variantName === "string" && variantName.length > 0) {
-    headers["x-to11-variant-name"] = variantName;
+  if (typeof prompt.variantName === "string" && prompt.variantName.length > 0) {
+    headers["x-to11-variant-name"] = prompt.variantName;
   }
-  if (prompt.labels.length > 0) {
-    headers["x-to11-prompt-labels"] = prompt.labels.join(",");
+  if (prompt.label.length > 0) {
+    headers["x-to11-prompt-label"] = prompt.label;
   }
   return headers;
 }
@@ -94,22 +93,44 @@ 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 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 msg = {
         role: "assistant",
         content: message.content ?? null
       };
       if (message.toolCalls != null && message.toolCalls.length > 0) {
-        out.tool_calls = message.toolCalls.map((call) => ({
+        msg.tool_calls = message.toolCalls.map((call) => ({
           id: requireToolCallId(call.id),
           type: "function",
           function: {
@@ -118,17 +139,22 @@ function toOpenAIMessages(messages) {
           }
         }));
       }
-      return out;
+      out.push(msg);
+      return;
     }
-    return { role: message.role, content: message.content ?? "" };
+    out.push({ 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",
@@ -140,7 +166,7 @@ function toAnthropicMessages(messages) {
           }
         ]
       });
-      continue;
+      return;
     }
     if (message.role === "assistant") {
       if (message.toolCalls != null && message.toolCalls.length > 0) {
@@ -160,18 +186,32 @@ 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;
+}
 export {
   toOpenAITools,
   toOpenAIToolChoice,
   toOpenAIMessages,
   toAnthropicTools,
   toAnthropicToolChoice,
+  toAnthropicSystem,
   toAnthropicMessages,
   gatewayPromptHeaders,
   gatewayAuthHeaders