@kitn.ai/ui 0.20.1 → 0.21.0

package/src/wire/encode.ts

@@ -0,0 +1,474 @@
+// 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';
+
+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>;
+
+export interface OpenAIWireMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | 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[];
+}
+
+export interface OpenAIEncodeOptions {
+  /**
+   * 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';
+}
+
+/** 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';
+
+const textOf = (parts: MessagePart[]): string =>
+  parts
+    .filter(isTextPart)
+    .map((p) => p.text)
+    .join('');
+
+/** 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`, `source` and `file` parts are never encoded; they are kit-side. File
+ * attachments are a documented v1 limitation, which is why a user turn carrying
+ * only an attachment encodes to nothing and is skipped.
+ */
+export function toOpenAIMessages(
+  messages: ChatMessage[],
+  options: OpenAIEncodeOptions = {},
+): OpenAIWireMessage[] {
+  const includeReasoning = options.reasoning === 'include';
+  const out: OpenAIWireMessage[] = [];
+
+  for (const message of messages) {
+    if (message.role === 'user') {
+      const content = textOf(message.parts);
+      if (content !== '') 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 = [];
+    };
+
+    for (const part of message.parts) {
+      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;
+        continue;
+      }
+      if (part.type === 'reasoning') {
+        if (!includeReasoning) 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);
+        continue;
+      }
+      if (part.type === 'tool' && isSettled(part.tool)) pending.push(part.tool);
+    }
+    flush();
+  }
+
+  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.
+ *
+ * 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[]): AnthropicWireMessage[] {
+  const out: AnthropicWireMessage[] = [];
+
+  /** 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 });
+  };
+
+  for (const message of messages) {
+    if (message.role === 'user') {
+      const userBlocks = message.parts
+        .filter(isTextPart)
+        .filter((p) => p.text !== '')
+        .map<AnthropicContentBlock>((p) => ({ type: 'text', text: p.text }));
+      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 = [];
+    };
+
+    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);
+          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 });
+          break;
+        }
+        case 'tool': {
+          const tool = part.tool;
+          if (!isSettled(tool)) break;
+          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, source and file are kit-side and have no wire representation
+          // in v1. File attachments in particular are a known limitation.
+          break;
+      }
+    });
+
+    flush();
+  }
+
+  return out;
+}