@kitn.ai/ui 0.27.0 → 0.29.0

package/src/wire/encode.ts

@@ -1,947 +0,0 @@
-// ChatMessage[] back onto the wire, so a host can run a multi-round tool loop in
-// about fifteen lines of its own code. The kit never calls a consumer's function
-// and never drives the loop; these two functions are the whole contribution.
-//
-// No provider SDK, no fetch, no DOM. Pure functions over the content model.
-import type { ChatMessage, MessagePart } from '../elements/chat-types';
-import type { ToolPart } from '../components/tool-types';
-import { classifyAttachment, textFileContent, type ClassifiedFile } from './files';
-import { resolveMediaPolicy, type MediaPolicy, type MediaTypeFilter } from './media-types';
-import { wireDiagnosticsActive, wirePayloadActive } from './diagnostics';
-import { base64Bytes, createEncodeProbe, type EncodeProbe } from './encode-probe';
-
-export interface OpenAIToolCall {
-  id: string;
-  type: 'function';
-  function: { name: string; arguments: string };
-}
-
-/** One `reasoning_details` entry. Provider-owned open shape, kept as a record
- *  for the same reason `AnthropicContentBlock` is: an opaque entry has to pass
- *  through UNTOUCHED, and a closed type would be a list of the fields we happen
- *  to have seen. */
-export type OpenAIReasoningDetail = Record<string, unknown>;
-
-/** A multimodal user message's content entries. `image_url` takes an https URL
- *  or a `data:` URI in the same field; `file` takes `file_data`, which is a DATA
- *  URI on this wire (`data:application/pdf;base64,...`) and not bare base64. */
-export type OpenAIContentPart =
-  | { type: 'text'; text: string }
-  | { type: 'image_url'; image_url: { url: string } }
-  | { type: 'file'; file: { filename?: string; file_data: string } };
-
-export interface OpenAIWireMessage {
-  role: 'system' | 'user' | 'assistant' | 'tool';
-  /** An ARRAY only when the turn carries an encodable `file` part. A text-only
-   *  turn stays a plain string, so adding attachment support changed nothing
-   *  about what an existing thread puts on the wire. */
-  content: string | OpenAIContentPart[] | null;
-  tool_calls?: OpenAIToolCall[];
-  tool_call_id?: string;
-  name?: string;
-  /** Only ever present when `toOpenAIMessages` was asked for it. See
-   *  `OpenAIEncodeOptions.reasoning`. */
-  reasoning_details?: OpenAIReasoningDetail[];
-}
-
-/** EXTENDS rather than restates the file options: `onUnencodableFile` and
- *  `accept` mean the same thing on both wires, and a second declaration of them
- *  here is a second place to forget to update. */
-export interface OpenAIEncodeOptions extends FileEncodeOptions {
-  /**
-   * Whether to send the assistant's own reasoning back with the thread.
-   *
-   * DEFAULT `'omit'`, and that default is a measurement, not caution. Omitting
-   * reasoning is accepted by every configuration tested -- five live omission
-   * trials plus 28 recorded live requests per configuration across the spike's
-   * conformance sweep, zero 400s -- so the path that ships today demonstrably
-   * works, while including reasoning cost about 25% more prompt tokens per round
-   * when measured (665 -> 834 on a two-round loop). A library does not get to
-   * raise every consumer's bill and add a new provider-validation surface as a
-   * side effect of a bug fix.
-   *
-   * `'include'` is for a multi-round TOOL loop, which is where OpenRouter says it
-   * pays: "when you post tool results, including the original reasoning ensures
-   * the model can continue its reasoning from where it left off". Measured
-   * accepted (HTTP 200) for a signed Anthropic block and for an OpenAI encrypted
-   * block, over the OpenAI-compatible wire.
-   *
-   * The Anthropic wire has no such knob because it has no such choice: a filtered
-   * or rebuilt thinking block there is a hard 400.
-   */
-  reasoning?: 'omit' | 'include';
-}
-
-/**
- * What to do with a `file` part this wire cannot carry.
- *
- * DEFAULT `'throw'`, and the default is the whole point. Skipping is how
- * attachments came to render perfectly in the thread and reach the model as
- * nothing: the developer wires up upload, watches it work, and ships a model
- * that cannot see the file. A throw here names the message, the part and the
- * reason, which is strictly more than a 400 at request time would tell you.
- *
- * `'skip'` restores the lenient behaviour for a host that would rather send a
- * degraded turn than fail one. It is silent, but it is silence the developer
- * asked for by name, which is the difference that matters.
- */
-export type UnencodableFilePolicy = 'throw' | 'skip';
-
-export interface FileEncodeOptions {
-  onUnencodableFile?: UnencodableFilePolicy;
-  /**
-   * Narrow which attachment media types reach the wire, as HTML `accept` syntax
-   * (`'image/*,application/pdf'`) or an array of the same.
-   *
-   * THE SAME STRING the composer takes as `<kai-chat accept="...">`, resolved by
-   * the same function against the same declaration -- so a developer writes the
-   * set once as a constant and hands it to both ends. Omitted means the kit's
-   * full capability set, which is `encodableMediaTypes()`.
-   *
-   * It can only NARROW. Naming a type the encoders cannot represent does not
-   * enable it; that would just move the failure to a provider 400.
-   */
-  accept?: MediaTypeFilter;
-  /**
-   * The app's own id for the logical turn this encode belongs to, carried onto
-   * every diagnostic event the encode emits. Purely diagnostic: nothing here
-   * branches on it and it never reaches a provider.
-   *
-   * THE SAME FIELD, THE SAME MEANING, as `ConsumeOptions.traceId` -- and that
-   * symmetry is the whole payoff. Encoding happens BEFORE a read opens, so
-   * there is no stream to attach an encode to and the kit will not invent one.
-   * Pass the same id to both halves:
-   *
-   *   const body = toOpenAIMessages(messages, { traceId: 'turn-42' });
-   *   readOpenAIStream(res, sink, { traceId: 'turn-42' });
-   *
-   * and the request and the response it produced sit together, with a tool loop
-   * or a sub-agent fan-out grouping into one trace. Without it you still see
-   * both halves; they are simply unlinked, which is the honest rendering --
-   * pinning an encode to "the next stream that opens" would be a guess, and an
-   * encode may be followed by no stream at all.
-   */
-  traceId?: string;
-  /** The app's name for this call inside its trace (`'planner'`, `'retry-2'`).
-   *  Same field and same meaning as `ConsumeOptions.label`. Absent when not
-   *  supplied. */
-  label?: string;
-}
-
-export type AnthropicEncodeOptions = FileEncodeOptions;
-
-/** Anthropic content blocks are an open, provider-owned union. Keeping them as
- *  records is what lets a verbatim `thinking` payload pass through UNTOUCHED,
- *  which is the entire point of this encoder. */
-export type AnthropicContentBlock = Record<string, unknown>;
-
-export interface AnthropicWireMessage {
-  role: 'user' | 'assistant';
-  content: AnthropicContentBlock[];
-}
-
-/** A message cannot be encoded without losing something the provider will reject.
- *  Thrown at encode time, on purpose: a throw here beats a 400 at request time,
- *  because here you still know which message and which part caused it. */
-export class WireEncodeError extends Error {
-  readonly messageId: string;
-  readonly partIndex: number;
-
-  constructor(message: string, messageId: string, partIndex: number) {
-    super(message);
-    // Restores the prototype chain when this class is DOWNLEVELLED to ES5 by a
-    // consumer's build, exactly as WireError does. Without it
-    // `err instanceof WireEncodeError` is false there and the documented way to
-    // catch an unencodable history stops working.
-    Object.setPrototypeOf(this, WireEncodeError.prototype);
-    this.name = 'WireEncodeError';
-    this.messageId = messageId;
-    this.partIndex = partIndex;
-  }
-}
-
-type TextPart = Extract<MessagePart, { type: 'text' }>;
-
-/** A tool that can be echoed back: it has the provider's own call id AND a
- *  result. Narrowing `toolCallId` to `string` here is what removes every
- *  non-null assertion downstream. */
-type SettledTool = ToolPart & { toolCallId: string };
-
-const isTextPart = (p: MessagePart): p is TextPart => p.type === 'text';
-
-// lint-silent-drops: drops reasoning,tool,card,source,file -- text projection by name and contract, used for the plain-string form of a turn; every caller that needs the other variants encodes them itself before falling back here.
-const textOf = (parts: MessagePart[]): string =>
-  parts
-    .filter(isTextPart)
-    .map((p) => p.text)
-    .join('');
-
-type FilePart = Extract<MessagePart, { type: 'file' }>;
-
-/** A wire either shapes a classified file into a block, or explains why it
- *  cannot. `ok: false` is NOT the same as an unencodable attachment: the
- *  attachment can be perfectly sound and still have no form on this particular
- *  wire, which is exactly the remote-PDF case on OpenAI. */
-type WireFileResult<T> = { ok: true; block: T } | { ok: false; reason: string };
-
-/**
- * One `file` part to one wire block, or `null` when it is skipped.
- *
- * Skipped means one of two things and never a third: the attachment is kit-side
- * (a citation chip), or the host explicitly opted into `onUnencodableFile:
- * 'skip'`. Everything else throws, because a dropped attachment is invisible in
- * exactly the way the developer needs it not to be.
- */
-function encodeFilePart<T>(
-  part: FilePart,
-  messageId: string,
-  partIndex: number,
-  policy: UnencodableFilePolicy,
-  media: MediaPolicy,
-  toBlock: (file: ClassifiedFile) => WireFileResult<T>,
-  probe: EncodeProbe | undefined,
-  messageIndex: number,
-): T | null {
-  const classified = classifyAttachment(part.attachment, media);
-  // What the HOST declared, which is the only label available on a path where
-  // classification never got as far as settling one.
-  const declared = part.attachment.mediaType;
-  const filename = part.attachment.filename;
-
-  if (classified.status === 'kit-side') {
-    // Reported in the attachment ledger, and NOT as a drop: a `source-document`
-    // is the citation chip beside a RAG answer, and its content is already in
-    // the prompt that produced that answer. Nothing was lost.
-    probe?.attachment(
-      {
-        ...(declared !== undefined ? { mediaType: declared } : {}),
-        encoded: false,
-        disposition: 'skipped',
-        reason:
-          'it is a kit-side attachment (a source-document citation chip), not something the user staged to send.',
-      },
-      filename,
-    );
-    return null;
-  }
-
-  const refuse = (reason: string, file?: ClassifiedFile): null => {
-    const mediaType = file?.mediaType ?? declared;
-    if (policy === 'skip') {
-      // THE SKIP THE DEVELOPER ASKED FOR BY NAME, now visible. It is still
-      // silent on the wire, exactly as documented; what changed is that the
-      // panel can say "this attachment rendered in the thread and was never
-      // sent", which is the sentence nobody could get out of the kit before.
-      probe?.attachment(
-        {
-          ...(mediaType !== undefined ? { mediaType } : {}),
-          ...bytesOf(file),
-          encoded: false,
-          disposition: 'skipped',
-          reason,
-        },
-        filename,
-      );
-      probe?.dropped('file', reason, messageIndex, partIndex, part);
-      return null;
-    }
-    throw new WireEncodeError(
-      `Cannot encode file part ${partIndex} of message "${messageId}": ${reason} Pass { onUnencodableFile: 'skip' } to drop it instead of failing.`,
-      messageId,
-      partIndex,
-    );
-  };
-
-  if (classified.status === 'unencodable') return refuse(classified.reason);
-
-  const shaped = toBlock(classified.file);
-  if (!shaped.ok) return refuse(shaped.reason, classified.file);
-
-  probe?.attachment(
-    {
-      mediaType: classified.file.mediaType,
-      ...bytesOf(classified.file),
-      encoded: true,
-      // A text file rides as text CONTENT on both wires -- worth naming
-      // separately, because it is how an attachment can be "sent" and still not
-      // be a file as far as the model is concerned.
-      disposition: classified.file.kind === 'text' ? 'as-text' : 'encoded',
-    },
-    filename,
-  );
-  return shaped.block;
-}
-
-/**
- * The size of what went on the wire, when it went on the wire at all.
- *
- * ★ GATED BEHIND PAYLOAD CAPTURE, for the same reason `encode.request.bytes`
- * is, and the deciding argument is that THE COST RECURS. The whole thread is
- * re-encoded on every turn, so a 10 MB attachment sitting in history is not a
- * one-time 4.3 ms -- it is 4.3 ms per turn for as long as a subscriber is
- * attached. Unbounded-per-turn is what fails "cheap enough to leave on", not
- * the absolute number.
- *
- * The diagnosis survives the omission: "your image/png attachment was skipped,
- * so the model never saw it" is the finding, and the size is a refinement of
- * it. `mediaType`, `encoded`, `disposition` and `reason` cost nothing and are
- * reported unconditionally. Arming payload gives exact sizes, which is
- * precisely the moment a developer has already accepted paying for content.
- *
- * ABSENT rather than estimated, always. For a remote attachment the provider
- * dereferences that URL itself and the bytes never enter this process; with
- * payload off the scan is simply not run. Both read as "not reported" under the
- * absence rule, and neither is ever backfilled with a guess -- see the rejected
- * candidates at `base64Bytes`.
- */
-function bytesOf(file?: ClassifiedFile): { bytes?: number } {
-  if (!wirePayloadActive()) return {};
-  if (file?.source.type !== 'base64') return {};
-  return { bytes: base64Bytes(file.source.data) };
-}
-
-/** `image_url` takes an https URL and a `data:` URI in the same field, so an
- *  image is one shape here. A PDF is not: `file_data` is base64-only. A text
- *  file is neither: it becomes ordinary text content, because that is the only
- *  thing either API's block set can express it as. */
-const openAIFileBlock = (file: ClassifiedFile): WireFileResult<OpenAIContentPart> => {
-  if (file.kind === 'text') {
-    return { ok: true, block: { type: 'text', text: textFileContent(file) } };
-  }
-
-  if (file.kind === 'image') {
-    const url = file.source.type === 'base64' ? file.source.dataUri : file.source.url;
-    return { ok: true, block: { type: 'image_url', image_url: { url } } };
-  }
-
-  if (file.source.type === 'remote') {
-    return {
-      ok: false,
-      reason: `it is a PDF at a remote URL ("${file.source.url}"), and a chat-completions \`file\` content part carries only \`file_id\` or \`file_data\` -- this wire has no URL form for a document. Fetch it and stage it as a \`data:\` URI, or upload it through the Files API and send \`file_id\` yourself; fetching it HERE would put I/O in the encoder. The Anthropic wire does take a remote PDF, so toAnthropicMessages accepts this same message.`,
-    };
-  }
-
-  return {
-    ok: true,
-    block: {
-      type: 'file',
-      file: {
-        ...(file.filename !== undefined ? { filename: file.filename } : {}),
-        file_data: file.source.dataUri,
-      },
-    },
-  };
-};
-
-/** The image and document blocks take the same two source shapes, which is why
- *  this wire has no gap where OpenAI has one. Text is the third case and is not
- *  a `document` block: this API's content-block set is text / image / document
- *  with no arbitrary-file member, so an inlined text file IS a text block.
- *  (A `document` block CAN carry text via the Files API, which would buy
- *  citations -- see the design note; it needs an upload step this layer cannot
- *  make, because it does no I/O.) */
-const anthropicFileBlock = (file: ClassifiedFile): WireFileResult<AnthropicContentBlock> => {
-  if (file.kind === 'text') {
-    return { ok: true, block: { type: 'text', text: textFileContent(file) } };
-  }
-
-  return {
-    ok: true,
-    block: {
-      type: file.kind === 'image' ? 'image' : 'document',
-      source:
-        file.source.type === 'base64'
-          ? { type: 'base64', media_type: file.source.mediaType, data: file.source.data }
-          : { type: 'url', url: file.source.url },
-    },
-  };
-};
-
-/** A tool is encodable only once it has a RESULT. Both APIs require every echoed
- *  tool call to have exactly one matching result, so a call with no answer yet is
- *  skipped entirely rather than sent half-formed. In a real loop the host
- *  executes tools before re-encoding, so this only drops genuinely pending work.
- *
- *  A tool with no `toolCallId` is skipped for the same reason: there is no id to
- *  correlate a result with, and synthesising one (`call_0`) produces a request
- *  the provider rejects. */
-const isSettled = (tool: ToolPart): tool is SettledTool =>
-  typeof tool.toolCallId === 'string' &&
-  tool.toolCallId !== '' &&
-  (tool.output !== undefined || tool.errorText !== undefined);
-
-/** The argument text to echo. `rawInput` is the raw accumulated fragments and is
- *  preferred: providers validate an echoed tool block against what they emitted,
- *  and re-stringifying a parse changes key order and whitespace. An EMPTY
- *  `rawInput` is not valid JSON, so it falls through to the parsed snapshot the
- *  same way an absent one does. */
-function argumentsOf(tool: ToolPart): string {
-  if (tool.rawInput !== undefined && tool.rawInput !== '') return tool.rawInput;
-  return tool.input !== undefined ? JSON.stringify(tool.input) : '{}';
-}
-
-const toolCallOf = (tool: SettledTool): OpenAIToolCall => ({
-  id: tool.toolCallId,
-  type: 'function',
-  function: { name: tool.type, arguments: argumentsOf(tool) },
-});
-
-/** `errorText` WINS over `output` when a part somehow carries both, on both
- *  wires. A host that reported a failure after a partial result meant the
- *  failure, and echoing a half-written success back to the model is the version
- *  of this that produces confidently wrong follow-up work. */
-const toolResultOf = (tool: SettledTool): OpenAIWireMessage => ({
-  role: 'tool',
-  tool_call_id: tool.toolCallId,
-  name: tool.type,
-  content: tool.errorText ?? JSON.stringify(tool.output),
-});
-
-type ReasoningPart = Extract<MessagePart, { type: 'reasoning' }>;
-
-const isRecord = (v: unknown): v is Record<string, unknown> =>
-  typeof v === 'object' && v !== null && !Array.isArray(v);
-
-/**
- * The provider's own `reasoning_details` entry for this block, if the part came
- * from the OpenAI wire at all.
- *
- * WHAT THIS IS NOT: the block. `part.raw` holds the LAST delta that touched this
- * part, because `appendReasoningPart` resolves `raw` last-write-wins, and every
- * reasoning-carrying provider streams its blocks in fragments. So this entry is
- * read for its SHAPE -- type, format, id, index, and an opaque payload if it has
- * one -- and never for its text.
- *
- * A delta carrying several entries at once is rare but legal, so the entry is
- * matched on the part's own block index first; that is the only correlator there
- * is. The last one wins otherwise, which is the entry `raw` was captured from.
- */
-function detailOf(part: ReasoningPart): Record<string, unknown> | undefined {
-  if (part.raw?.source !== 'openai.reasoning_details') return undefined;
-  const payload = part.raw.payload;
-  if (!Array.isArray(payload)) return undefined;
-  const records = payload.filter(isRecord);
-  const matched = records.filter((d) => d.index === part.index);
-  const pool = matched.length > 0 ? matched : records;
-  return pool[pool.length - 1];
-}
-
-/**
- * ONE reasoning part to ONE `reasoning_details` entry, or nothing.
- *
- * Three cases, and every one of them is in a recorded fixture:
- *
- * 1. OPAQUE (`reasoning.encrypted`, `openai/gpt-5.4-mini`). The `data` blob is
- *    the block; there is no text and no signature to rebuild it from, and it
- *    arrives whole in a single frame, so `raw` really is the block here. It goes
- *    back BY REFERENCE, untouched.
- *
- * 2. SIGNED (`reasoning.text` with a signature, an Anthropic model over this
- *    wire). REASSEMBLED from `part.text` and `part.signature`, never echoed.
- *    Echoing `raw` sends the final frame, which carries the signature and NO
- *    text -- measured: of 85 reasoning frames in one turn, only the last has the
- *    signature and it has no text. The signature is the load-bearing field:
- *    stripping it is a hard 400 (`Invalid signature in thinking block`) from all
- *    four providers OpenRouter tried, while mutating the text was accepted.
- *
- * 3. NEITHER (`deepseek` `format: "unknown"`, and the `reasoning.summary`
- *    entries that ride alongside gpt-5.4-mini's encrypted block). SKIPPED.
- *    Nothing measured supports sending these: the two accepted round-trips were
- *    a signed block and an encrypted one, and every measured 400 was a provider
- *    failing to verify a block it was handed. Omission, by contrast, is proven
- *    accepted everywhere. `format: "unknown"` is OpenRouter saying it could not
- *    attribute the block to a round-trippable format, and re-sending a summary
- *    OpenAI itself treats as a display artifact spends tokens on nothing.
- *
- * On the sequence rule -- "the entire sequence of consecutive reasoning blocks
- * must match the outputs generated by the model" -- case 3 is the one place this
- * is READ rather than proven. It holds up because verifiability is a
- * per-configuration property in all 40 recorded reasoning turns, never a
- * per-block one: Haiku signs every block, deepseek signs none, gpt-5.4-mini
- * signs none but carries `data`. So the skip never filters one block out of a
- * run of comparable ones. For gpt-5.4-mini it drops the summary at block index 0
- * and keeps the encrypted carrier at index 1, which is exactly the single-entry
- * payload the live probe sent and got a 200 for.
- */
-function reasoningDetailOf(part: ReasoningPart): OpenAIReasoningDetail | undefined {
-  const detail = detailOf(part);
-  if (!detail) return undefined;
-
-  if (detail.type === 'reasoning.encrypted' || typeof detail.data === 'string') return detail;
-
-  if (typeof part.signature !== 'string' || part.signature === '') return undefined;
-
-  const type = typeof detail.type === 'string' ? detail.type : 'reasoning.text';
-  // The readable field is named for the entry type: `summary` entries carry
-  // `summary`, everything else carries `text`.
-  const textKey = type === 'reasoning.summary' ? 'summary' : 'text';
-  const out: OpenAIReasoningDetail = { type, [textKey]: part.text, signature: part.signature };
-  if (typeof detail.format === 'string') out.format = detail.format;
-  if (typeof detail.id === 'string') out.id = detail.id;
-  if (detail.index !== undefined) out.index = detail.index;
-  return out;
-}
-
-/**
- * ChatMessage[] to an OpenAI chat-completions `messages` array.
- *
- * ONE ChatMessage CAN BECOME SEVERAL WIRE MESSAGES. The kit streams a whole
- * assistant turn into a single message, so text, a tool call and the model's
- * answer to that call all live in one `parts` array. The OpenAI wire has no such
- * shape: a `role:'tool'` result must sit between the assistant message that
- * announced the call and whatever the model said afterwards. So the turn is
- * SPLIT at each tool boundary, into
- *
- *   assistant(pre-tool text + tool_calls) -> tool(result)... -> assistant(answer)
- *
- * Flattening instead would put the model's answer BEFORE the result it was based
- * on. No endpoint rejects that, which is exactly why it is worth spelling out:
- * it quietly degrades every later round of a tool loop.
- *
- * Consecutive tool parts stay in ONE assistant message, because parallel calls
- * are announced together and their results follow together.
- *
- * A turn that encodes to nothing is SKIPPED, never sent as `{ content: null }`
- * with no `tool_calls`: OpenAI treats `content` as required unless `tool_calls`
- * is present, and strict-compatible endpoints reject it.
- *
- * REASONING IS OPT-IN, and off by default. OpenRouter's OpenAI-compatible
- * endpoint does have a channel on the way back in -- `reasoning_details` on the
- * assistant message -- and `{ reasoning: 'include' }` uses it, one entry per
- * reasoning part, in part order, reassembled by `reasoningDetailOf` rather than
- * echoed out of `part.raw`. Read that function for which blocks make it and why.
- * The default omits, because omitting is measured-accepted everywhere and costs
- * about 25% fewer prompt tokens per round; see `OpenAIEncodeOptions.reasoning`.
- *
- * Reasoning alone still encodes to NOTHING. A block is content the model already
- * produced, not a reason to send a turn, so a message carrying reasoning and no
- * text and no settled tool is skipped exactly as before, rather than becoming
- * `{ content: null }` with no `tool_calls`.
- *
- * `card` and `source` parts are never encoded; they are kit-side.
- *
- * `file` parts ARE encoded, on a USER turn, and a turn carrying nothing but an
- * attachment is now a real message rather than nothing. Images become
- * `image_url` (https URL or `data:` URI alike); a base64 PDF becomes a `file`
- * part whose `file_data` is the data URI. Two cases have no form here and THROW
- * by default: a remote PDF, because this wire's `file` part has no URL variant,
- * and anything that is neither -- see `UnencodableFilePolicy` for why the
- * default is a throw and not a skip.
- *
- * A `file` part on an ASSISTANT turn is still dropped. Neither API accepts image
- * or document content in an assistant message, so there is nothing to encode it
- * to; attachments belong to the user turn that sent them.
- */
-// lint-silent-drops: drops card,source -- kit-side parts with no OpenAI wire representation; cards come from tool calls, which ARE encoded, and sources are UI citations.
-export function toOpenAIMessages(
-  messages: ChatMessage[],
-  options: OpenAIEncodeOptions = {},
-): OpenAIWireMessage[] {
-  const includeReasoning = options.reasoning === 'include';
-  const filePolicy = options.onUnencodableFile ?? 'throw';
-  const media = resolveMediaPolicy({ accept: options.accept });
-  const out: OpenAIWireMessage[] = [];
-
-  // Gated BEFORE anything is allocated, so with nobody listening this whole
-  // ledger costs one symbol read for the entire encode.
-  const probe = wireDiagnosticsActive() ? createEncodeProbe(options) : undefined;
-  if (probe) {
-    for (const message of messages) for (const part of message.parts) probe.seen(part.type);
-  }
-
-  let messageIndex = -1;
-  for (const message of messages) {
-    messageIndex++;
-    if (message.role === 'user') {
-      // Built in PART ORDER, with runs of adjacent text merged into one entry.
-      // A file authored after the text stays after it: `parts` is an ordered
-      // content model and reordering it here would be the encoder second-guessing
-      // the author. Anthropic's docs do suggest putting images before text for
-      // best results, which is guidance for whoever builds the parts array.
-      const content: OpenAIContentPart[] = [];
-      let buffered = '';
-      let carriesFile = false;
-
-      const flushText = (): void => {
-        if (buffered === '') return;
-        content.push({ type: 'text', text: buffered });
-        buffered = '';
-      };
-
-      // lint-silent-drops: drops reasoning,tool,card,source -- a USER turn carries authored content only; reasoning and tool parts are assistant-side, cards and sources are kit-side UI with no OpenAI wire form.
-      message.parts.forEach((part, partIndex) => {
-        if (part.type === 'text') {
-          buffered += part.text;
-          if (part.text !== '') probe?.encoded('text');
-          return;
-        }
-        if (part.type !== 'file') {
-          // The drop the waiver above declares, now also reported. `part.type`
-          // is read off a part this branch has ALREADY discriminated -- no new
-          // switch, which is what keeps `lint:silent-drops` looking at exactly
-          // the sites it looked at before.
-          probe?.dropped(
-            part.type,
-            'a USER turn carries authored content only: reasoning and tool parts are assistant-side, and cards and sources are kit-side UI with no OpenAI wire form.',
-            messageIndex,
-            partIndex,
-            part,
-          );
-          return;
-        }
-        const block = encodeFilePart(
-          part,
-          message.id,
-          partIndex,
-          filePolicy,
-          media,
-          openAIFileBlock,
-          probe,
-          messageIndex,
-        );
-        if (!block) return;
-        flushText();
-        content.push(block);
-        probe?.encoded('file');
-        carriesFile = true;
-      });
-      flushText();
-
-      // No file survived, so this is an ordinary turn and stays a plain string.
-      if (!carriesFile) {
-        // `textOf`'s own waiver names the same drops the callback above just
-        // reported, over the same parts array in the same branch. Reporting them
-        // again HERE would double-count every card and source in a user turn, so
-        // the callback is the single site and this one deliberately stays quiet.
-        const text = textOf(message.parts);
-        if (text !== '') out.push({ role: 'user', content: text });
-        continue;
-      }
-      out.push({ role: 'user', content });
-      continue;
-    }
-
-    let text = '';
-    let pending: SettledTool[] = [];
-    let reasoning: OpenAIReasoningDetail[] = [];
-
-    /** Emit the assistant message for everything buffered so far, then the
-     *  result message for each call it announced, in the same order.
-     *
-     *  The early return leaves any buffered reasoning where it is on purpose:
-     *  nothing was emitted, so those blocks still belong to a message that has
-     *  not been written yet. In practice it is unreachable with reasoning
-     *  buffered, because the only mid-loop `flush()` runs with `pending`
-     *  non-empty. */
-    const flush = (): void => {
-      if (text === '' && pending.length === 0) return;
-      out.push({
-        role: 'assistant',
-        content: text === '' ? null : text,
-        ...(reasoning.length > 0 ? { reasoning_details: reasoning } : {}),
-        ...(pending.length > 0 ? { tool_calls: pending.map(toolCallOf) } : {}),
-      });
-      for (const tool of pending) out.push(toolResultOf(tool));
-      text = '';
-      pending = [];
-      reasoning = [];
-    };
-
-    let partIndex = -1;
-    for (const part of message.parts) {
-      partIndex++;
-      if (part.type === 'text') {
-        // Text that arrives AFTER a call is the model's answer to it, so the
-        // call and its result have to be on the wire before this text is.
-        if (pending.length > 0) flush();
-        text += part.text;
-        if (part.text !== '') probe?.encoded('text');
-        continue;
-      }
-      if (part.type === 'reasoning') {
-        if (!includeReasoning) {
-          probe?.dropped(
-            'reasoning',
-            "reasoning is omitted by default, because omitting is measured-accepted everywhere and costs about 25% fewer prompt tokens per round. Pass { reasoning: 'include' } to send the model its own prior thinking back.",
-            messageIndex,
-            partIndex,
-            part,
-          );
-          continue;
-        }
-        // A block after a call belongs to the round that READ the result, for the
-        // same reason text does. Same rule as `toAnthropicMessages`.
-        if (pending.length > 0) flush();
-        const detail = reasoningDetailOf(part);
-        if (detail) {
-          reasoning.push(detail);
-          probe?.encoded('reasoning');
-          continue;
-        }
-        // ★ THE REASONING ROUND TRIP, reported rather than changed. `detailOf`
-        // only produces an entry for a part whose `raw` came from
-        // `openai.reasoning_details`, so a part read off `reasoning_content`
-        // (DeepSeek-direct) has no round-trippable carrier and is not echoed --
-        // and the model loses its own prior thinking on the next turn. The
-        // ruling stands and is deliberate; what changes here is that it is
-        // visible. See `reasoningDetailOf` for which blocks make it and why.
-        probe?.dropped(
-          'reasoning',
-          'it has no round-trippable `reasoning_details` carrier -- an opaque or signed block can be echoed back, but a part read from `reasoning_content` has neither, and re-sending an unverifiable block is the documented 400. The model does not see its own prior thinking on the next turn.',
-          messageIndex,
-          partIndex,
-          part,
-        );
-        continue;
-      }
-      if (part.type === 'tool') {
-        if (isSettled(part.tool)) {
-          pending.push(part.tool);
-          probe?.encoded('tool');
-        } else {
-          probe?.dropped(
-            'tool',
-            'the call has no result yet (or no provider tool call id). Both APIs require every echoed tool call to have exactly one matching result, so a half-formed one is left off rather than sent.',
-            messageIndex,
-            partIndex,
-            part,
-          );
-        }
-        continue;
-      }
-      // card, source, and a `file` part on an ASSISTANT turn. Same parts the
-      // function's waiver names, read off a part already discriminated above.
-      probe?.dropped(
-        part.type,
-        'cards and sources are kit-side UI with no OpenAI wire form, and a `file` part on an ASSISTANT turn has none either -- the API takes image and document content on user turns only.',
-        messageIndex,
-        partIndex,
-        part,
-      );
-    }
-    flush();
-  }
-
-  probe?.finish('openai', messages.length, out);
-  return out;
-}
-
-/**
- * ChatMessage[] to an Anthropic Messages `messages` array. THE ROUND-TRIP
- * ENCODER.
- *
- * A reasoning block is emitted as `part.raw.payload` verbatim and is NEVER
- * rebuilt from `text` plus `signature`: Anthropic returns 400 if a thinking
- * block in the most recent assistant message is modified, reordered, filtered or
- * reconstructed. A reasoning part with no `raw`, or with a `raw` captured from
- * some other format, therefore THROWS rather than silently producing a request
- * that will fail.
- *
- * Block order follows part order, which follows stream order, with no filtering,
- * because the API validates order too. An empty-text reasoning part (an omitted
- * or redacted block) is still emitted: the docs require sending back every block
- * "including any blocks with empty thinking fields".
- *
- * ONE ChatMessage CAN BECOME SEVERAL WIRE MESSAGES, for the same reason as
- * `toOpenAIMessages`: the kit streams a whole assistant turn into one message, so
- * the tool call and the model's answer to it share a `parts` array, but Anthropic
- * carries the result in a SEPARATE user message that has to sit between them. So
- * the turn is SPLIT at each tool boundary, into
- *
- *   assistant(pre-tool blocks + tool_use) -> user(tool_result)... -> assistant(answer)
- *
- * Flattening instead puts the model's answer BEFORE the result it was based on,
- * and strands every later round's thinking block in the first assistant message.
- * Consecutive tool parts stay in ONE assistant message, because parallel calls are
- * announced together and their results come back together.
- *
- * Adjacent user messages are MERGED. The API combines consecutive same-role turns
- * itself rather than rejecting them, so this is not what stands between you and a
- * 400; it is emitted anyway because the tool-result turn and a following user turn
- * are one turn, several OpenAI-compatible Anthropic proxies do enforce strict
- * alternation, and the merged form is what the models are trained on. Ordering is
- * safe by construction: `results` is only non-empty when `blocks` is, so a
- * tool_result message always follows its assistant message and can never be
- * appended after a plain user turn.
- *
- * `file` parts on a USER turn become `image` and `document` blocks, in part
- * order. Both take `source: {type:'base64'}` and `source: {type:'url'}`, so this
- * wire can carry a remote PDF that `toOpenAIMessages` has to refuse. Anything
- * neither API accepts as message content THROWS by default; see
- * `UnencodableFilePolicy`. A `file` part on an ASSISTANT turn is dropped, because
- * an assistant message here carries only text, thinking and tool_use.
- *
- * Asymmetry worth knowing: `tool_use.input` is a parsed OBJECT on this wire, not
- * a string, so it uses `input` and not `rawInput`. Only thinking blocks carry a
- * verbatim requirement.
- */
-export function toAnthropicMessages(
-  messages: ChatMessage[],
-  options: AnthropicEncodeOptions = {},
-): AnthropicWireMessage[] {
-  const filePolicy = options.onUnencodableFile ?? 'throw';
-  const media = resolveMediaPolicy({ accept: options.accept });
-  const out: AnthropicWireMessage[] = [];
-
-  // Gated before anything is allocated, exactly as in `toOpenAIMessages`.
-  const probe = wireDiagnosticsActive() ? createEncodeProbe(options) : undefined;
-  if (probe) {
-    for (const message of messages) for (const part of message.parts) probe.seen(part.type);
-  }
-
-  /** Append to the trailing user message when there is one, so the wire never
-   *  carries two user turns in a row. */
-  const pushUser = (content: AnthropicContentBlock[]): void => {
-    const last = out[out.length - 1];
-    if (last?.role === 'user') last.content = [...last.content, ...content];
-    else out.push({ role: 'user', content });
-  };
-
-  let messageIndex = -1;
-  for (const message of messages) {
-    messageIndex++;
-    if (message.role === 'user') {
-      // Part order, for the same reason as `toOpenAIMessages`.
-      const userBlocks: AnthropicContentBlock[] = [];
-      // lint-silent-drops: drops reasoning,tool,card,source -- a USER turn carries authored content only; reasoning and tool parts are assistant-side, cards and sources are kit-side UI with no Anthropic wire form.
-      message.parts.forEach((part, partIndex) => {
-        if (part.type === 'text') {
-          if (part.text !== '') {
-            userBlocks.push({ type: 'text', text: part.text });
-            probe?.encoded('text');
-          }
-          return;
-        }
-        if (part.type !== 'file') {
-          // The drop this callback's waiver declares, reported. `part.type` is
-          // read off a part the branch already discriminated.
-          probe?.dropped(
-            part.type,
-            'a USER turn carries authored content only: reasoning and tool parts are assistant-side, and cards and sources are kit-side UI with no Anthropic wire form.',
-            messageIndex,
-            partIndex,
-            part,
-          );
-          return;
-        }
-        const block = encodeFilePart(
-          part,
-          message.id,
-          partIndex,
-          filePolicy,
-          media,
-          anthropicFileBlock,
-          probe,
-          messageIndex,
-        );
-        if (block) {
-          userBlocks.push(block);
-          probe?.encoded('file');
-        }
-      });
-      if (userBlocks.length > 0) pushUser(userBlocks);
-      continue;
-    }
-
-    let blocks: AnthropicContentBlock[] = [];
-    let results: AnthropicContentBlock[] = [];
-
-    /** Emit the assistant message built so far, then the user message carrying the
-     *  results of the calls it announced. */
-    const flush = (): void => {
-      if (blocks.length > 0) out.push({ role: 'assistant', content: blocks });
-      // Anthropic carries tool results in the FOLLOWING user message.
-      if (results.length > 0) pushUser(results);
-      blocks = [];
-      results = [];
-    };
-
-    // lint-silent-drops: drops card,source,file -- cards and sources are kit-side UI; a file part on an ASSISTANT turn has no Anthropic representation, since the API takes image and document content on user turns only.
-    message.parts.forEach((part, partIndex) => {
-      switch (part.type) {
-        case 'reasoning': {
-          if (!part.raw) {
-            throw new WireEncodeError(
-              `Cannot encode reasoning part ${partIndex} of message "${message.id}": it has no \`raw\` payload, and Anthropic requires a thinking block to be echoed back verbatim. Rebuilding one from text plus signature is the documented 400. Produce reasoning parts with readAnthropicStream, which attaches the provider's own block, and keep \`raw\` when you persist a message.`,
-              message.id,
-              partIndex,
-            );
-          }
-          if (!part.raw.source.startsWith('anthropic.')) {
-            throw new WireEncodeError(
-              `Cannot encode reasoning part ${partIndex} of message "${message.id}": its \`raw\` came from "${part.raw.source}", not from the Anthropic Messages format. Only a payload tagged \`anthropic.\` can be echoed back verbatim. If you are talking to an Anthropic model through an OpenAI-compatible endpoint, use toOpenAIMessages.`,
-              message.id,
-              partIndex,
-            );
-          }
-          // A thinking block after a call belongs to the round that READ the
-          // result, so the result has to be on the wire before it is.
-          if (results.length > 0) flush();
-          blocks.push(part.raw.payload as AnthropicContentBlock);
-          probe?.encoded('reasoning');
-          break;
-        }
-        case 'text': {
-          if (part.text === '') break;
-          // Text after a call is the model's answer to it. Same reason.
-          if (results.length > 0) flush();
-          blocks.push({ type: 'text', text: part.text });
-          probe?.encoded('text');
-          break;
-        }
-        case 'tool': {
-          const tool = part.tool;
-          if (!isSettled(tool)) {
-            probe?.dropped(
-              'tool',
-              'the call has no result yet (or no provider tool call id). Both APIs require every echoed tool call to have exactly one matching result, so a half-formed one is left off rather than sent.',
-              messageIndex,
-              partIndex,
-              part,
-            );
-            break;
-          }
-          probe?.encoded('tool');
-          blocks.push({
-            type: 'tool_use',
-            id: tool.toolCallId,
-            name: tool.type,
-            input: tool.input ?? {},
-          });
-          results.push(
-            tool.errorText !== undefined
-              ? {
-                  type: 'tool_result',
-                  tool_use_id: tool.toolCallId,
-                  is_error: true,
-                  content: tool.errorText,
-                }
-              : {
-                  type: 'tool_result',
-                  tool_use_id: tool.toolCallId,
-                  content: JSON.stringify(tool.output),
-                },
-          );
-          break;
-        }
-        default:
-          // card and source are kit-side. A `file` part reaches this arm only on
-          // an ASSISTANT turn, where the API accepts no image or document
-          // content at all -- user attachments are handled in the user branch.
-          probe?.dropped(
-            part.type,
-            'cards and sources are kit-side UI, and a `file` part on an ASSISTANT turn has no Anthropic representation -- the API takes image and document content on user turns only.',
-            messageIndex,
-            partIndex,
-            part,
-          );
-          break;
-      }
-    });
-
-    flush();
-  }
-
-  probe?.finish('anthropic', messages.length, out);
-  return out;
-}