@ultimat3/ai 27.8.1 → 27.10.0

package/src/openai-provider.ts

@@ -9,14 +9,16 @@
 
 import type { Secret } from '@ultimat3/core';
 import { isSecret, revealSecret } from '@ultimat3/core';
+import { costOf, exactCostOf } from './cost';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
 import type { AiFetch } from './fetch-seam';
 import { resolveModel } from './model-resolve';
 import type { ModelId } from './models';
-import { chatCompletionBody } from './openai-body';
+import { chatCompletionBody, sessionHeaders } from './openai-body';
 import type { ChatAnswer } from './openai-wire';
 import { ChatCompletionStream, parseChatCompletion } from './openai-wire';
+import { promptCacheRule } from './prompt-cache';
 import type {
   GenerateRequest,
   GenerateResult,
@@ -24,8 +26,9 @@ import type {
   StreamChunk,
   TokenUsage,
 } from './provider';
-import { costOf, estimateInputTokens, estimateTextTokens, requiresStreaming } from './provider';
+import { estimateInputTokens, estimateTextTokens, requiresStreaming } from './provider';
 import { readSse } from './sse';
+import { assertToolArguments } from './tool-arguments';
 import type { LlmToolCall } from './tools';
 
 const API_KEY_ENV = 'OPENAI_API_KEY';
@@ -84,6 +87,7 @@ export function openAiProvider(input: OpenAiProviderInput): Provider {
 }
 
 class OpenAiProvider implements Provider {
+  readonly wire = 'openai' as const;
   readonly name: string;
   readonly models: readonly ModelId[];
   private readonly config: OpenAiProviderInput;
@@ -105,6 +109,10 @@ class OpenAiProvider implements Provider {
     this.config = config;
   }
 
+  marksPromptCache(model: ModelId): boolean {
+    return promptCacheRule('openai', this.config.baseUrl, model).marks === 'parts';
+  }
+
   /**
    * Above `STREAM_ONLY_MAX_TOKENS` this runs the streaming transport and assembles the result,
    * for the reason the Anthropic provider does: a non-streaming request that large sits on an
@@ -115,10 +123,12 @@ class OpenAiProvider implements Provider {
     // this provider's first listed model — the app's three places are the only ones.
     const model = resolveModel('provider', request.model);
     if (requiresStreaming({ ...request, model })) return this.assemble(request);
+    const { baseUrl } = this.config;
     const response = await this.send(
-      chatCompletionBody({ request, model, stream: false, provider: this.name }),
+      chatCompletionBody({ request, model, stream: false, provider: this.name, baseUrl }),
       false,
       request.signal,
+      sessionHeaders(request, model, baseUrl),
     );
     const answer = parseChatCompletion((await response.json()) as unknown, this.name);
     return this.result(request, model, answer);
@@ -126,10 +136,12 @@ class OpenAiProvider implements Provider {
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = resolveModel('provider', request.model);
+    const { baseUrl } = this.config;
     const response = await this.send(
-      chatCompletionBody({ request, model, stream: true, provider: this.name }),
+      chatCompletionBody({ request, model, stream: true, provider: this.name, baseUrl }),
       true,
       request.signal,
+      sessionHeaders(request, model, baseUrl),
     );
     if (response.body === null) {
       throw new AiTransportError({
@@ -142,6 +154,8 @@ class OpenAiProvider implements Provider {
     for await (const frame of readSse(response.body, this.name)) {
       for (const chunk of completion.push(frame)) yield chunk;
     }
+    // The socket closed: the calls of a finished turn, for a server that never sends `[DONE]`.
+    for (const chunk of completion.end()) yield chunk;
     // A connection cut mid-answer must fail, not resolve: partial text reads as a complete answer,
     // and `end_turn` would be a lie the caller has no way to detect.
     if (!completion.isComplete()) {
@@ -167,6 +181,9 @@ class OpenAiProvider implements Provider {
   /** One parsed answer, priced. The only place `cost` is applied — the provider owns prices. */
   private result(request: GenerateRequest, model: ModelId, answer: ChatAnswer): GenerateResult {
     const usage = answer.usage ?? estimatedUsage(request, answer.text, answer.toolCalls);
+    const cost = costOf(model, usage);
+    // After usage is known, so a finished turn with unreadable arguments fails WITH its bill.
+    assertToolArguments({ provider: this.name, model, ...answer, usage, cost });
     return {
       model,
       text: answer.text,
@@ -174,7 +191,8 @@ class OpenAiProvider implements Provider {
       stopReason: answer.stopReason,
       stopDetails: answer.stopDetails,
       usage,
-      cost: costOf(model, usage),
+      cost,
+      costExact: exactCostOf(model, usage),
     };
   }
 
@@ -187,6 +205,7 @@ class OpenAiProvider implements Provider {
     body: Record<string, unknown>,
     streaming: boolean,
     signal: AbortSignal | undefined,
+    extra: Readonly<Record<string, string>>,
   ): Promise<Response> {
     const apiKey = this.apiKey();
     const doFetch: AiFetch = this.config.fetch ?? fetch;
@@ -198,6 +217,8 @@ class OpenAiProvider implements Provider {
           : { authorization: `Bearer ${apiKey}` }),
         'content-type': 'application/json',
         accept: streaming ? 'text/event-stream' : 'application/json',
+        // The prompt-cache session, when the request carries one and this host routes by it.
+        ...extra,
         // Last, so a caller can replace the credential header outright for a gateway that wants
         // its own scheme. Nothing here is ever logged.
         ...this.config.headers,

package/src/openai-wire.ts

@@ -10,6 +10,8 @@ import { renderThrowable } from '@ultimat3/core';
 import { AiTransportError } from './errors';
 import type { StopDetails, StopReason, StreamChunk, TokenUsage } from './provider';
 import type { SseFrame } from './sse';
+import type { MalformedToolCall } from './tool-arguments';
+import { parseToolArguments } from './tool-arguments';
 import type { LlmToolCall } from './tools';
 
 /**
@@ -20,9 +22,16 @@ import type { LlmToolCall } from './tools';
 export interface ChatAnswer {
   readonly text: string;
   readonly toolCalls: readonly LlmToolCall[];
+  /**
+   * Calls whose arguments were not JSON. Never among `toolCalls` — a fragment is never a call —
+   * and what they mean is the provider's decision (`assertToolArguments`), once usage is known.
+   */
+  readonly malformed: readonly MalformedToolCall[];
   readonly stopReason: StopReason;
   readonly stopDetails: StopDetails | undefined;
   readonly usage: TokenUsage | undefined;
+  /** The raw finish reason when this build does not know it — `stopReason` is then read off the content. */
+  readonly unknownFinish?: string;
 }
 
 // A `Map`, not an object literal: `raw` is the PROVIDER's string on every read, and
@@ -33,14 +42,46 @@ export interface ChatAnswer {
 const FINISH_REASONS: ReadonlyMap<string, StopReason> = new Map(
   Object.entries({
     stop: 'end_turn',
+    // Synonyms for "the model finished", as endpoints in the family spell it: the Messages API's
+    // word passed through by a gateway, a tokenizer's end-of-sequence, Gemini's `STOP`.
+    end_turn: 'end_turn',
+    eos: 'end_turn',
+    eos_token: 'end_turn',
+    stop_sequence: 'stop_sequence',
     length: 'max_tokens',
+    max_tokens: 'max_tokens',
+    model_context_window_exceeded: 'model_context_window_exceeded',
     tool_calls: 'tool_use',
     // The legacy name for the same event; LiteLLM and older self-hosted servers still send it.
     function_call: 'tool_use',
+    tool_use: 'tool_use',
     content_filter: 'refusal',
   } as const),
 );
 
+/** What a `finish_reason` field said: nothing yet, a reason this build knows, or one it does not. */
+export type FinishReading =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'known'; readonly reason: StopReason }
+  | { readonly kind: 'unknown'; readonly raw: string };
+
+/**
+ * Read a finish reason, case-insensitively (`STOP`, `MAX_TOKENS`). A non-string (`null` on a
+ * delta) is "still going". A string this table does not list is UNKNOWN, and deliberately not
+ * truncation: `llm()` and `agent()` refuse a truncated turn before reading it, so guessing
+ * "cut off" fails every call of an endpoint that merely spells "done" its own way. What an unknown
+ * reason amounts to is decided from the answer itself (`unknownFinishReason`), by the provider.
+ */
+export function readFinishReason(raw: unknown): FinishReading {
+  if (typeof raw !== 'string') return { kind: 'none' };
+  const reason = FINISH_REASONS.get(raw) ?? FINISH_REASONS.get(raw.toLowerCase());
+  return reason === undefined ? { kind: 'unknown', raw } : { kind: 'known', reason };
+}
+
+/** The stop reason of a turn whose finish reason is unknown: what its content shows it to be. */
+const settledAs = (calls: readonly LlmToolCall[]): StopReason =>
+  calls.length > 0 ? 'tool_use' : 'end_turn';
+
 /**
  * In-band error frames carry a type, not a status, and the gateway's retry rule reads a status.
  * Same mapping job as wire.ts's, over this format's own vocabulary.
@@ -63,21 +104,26 @@ const ERROR_STATUS: ReadonlyMap<string, number> = new Map(
 );
 
 /**
- * The finish reason, or `undefined` for a non-string (`null` on a delta means "still going").
- * A string this table does not know FAILS CLOSED as `max_tokens` — `wire.ts`'s `parseStopReason`
- * rule, so one unknown reason reads the same on both formats: a provider's new reason is far
- * likelier to be a way of stopping early than of finishing.
+ * The finish reason as a `StopReason`, or `undefined` for a non-string. An UNKNOWN string reads
+ * `end_turn` here — the bare lookup has no answer to judge it by; the two readers below do, and
+ * report the raw reason as `unknownFinish` so the provider can refuse a turn that is not whole.
  */
 export function parseFinishReason(raw: unknown): StopReason | undefined {
-  return typeof raw === 'string' ? (FINISH_REASONS.get(raw) ?? 'max_tokens') : undefined;
+  const read = readFinishReason(raw);
+  return read.kind === 'none' ? undefined : read.kind === 'known' ? read.reason : 'end_turn';
 }
 
 /**
  * `usage`, or `undefined` when the payload carried none.
  *
- * `prompt_tokens` INCLUDES the cached prefix on this wire, where Anthropic's `input_tokens`
- * excludes it — so the cached half is subtracted out before it is reported as `cacheReadTokens`.
- * Left in place it would be billed twice: once at the full input rate and again at the cache rate.
+ * `prompt_tokens` is the WHOLE prompt on this wire — the part read from a cache and the part
+ * written to one included — where Anthropic's `input_tokens` excludes both. So both are subtracted
+ * out before they are reported under their own counters. Left in place a cached token would be
+ * billed twice: once at the full input rate and again at the cache rate.
+ *
+ * `cache_write_tokens` is OpenRouter's (`prompt_tokens_details.cache_write_tokens`, "Number of
+ * tokens written to the cache"), reported for a model whose vendor bills a write. An endpoint that
+ * never sends it — OpenAI's own, where a write is free — reads as zero.
  */
 export function parseOpenAiUsage(raw: unknown): TokenUsage | undefined {
   const record = asRecord(raw);
@@ -85,14 +131,18 @@ export function parseOpenAiUsage(raw: unknown): TokenUsage | undefined {
   const prompt = countOf(record['prompt_tokens']);
   const completion = countOf(record['completion_tokens']);
   if (prompt === undefined && completion === undefined) return undefined;
-  const cached = countOf(asRecord(record['prompt_tokens_details'])?.['cached_tokens']) ?? 0;
+  const details = asRecord(record['prompt_tokens_details']);
+  const total = prompt ?? 0;
+  // Each clamped to what is left of the prompt: a counter larger than the prompt it is part of is
+  // the endpoint's mistake, and an unclamped one bills tokens that were never sent.
+  const cached = Math.min(countOf(details?.['cached_tokens']) ?? 0, total);
+  const written = Math.min(countOf(details?.['cache_write_tokens']) ?? 0, total - cached);
   return {
-    inputTokens: Math.max((prompt ?? 0) - cached, 0),
+    inputTokens: total - cached - written,
     // `completion_tokens` already contains `reasoning_tokens`; adding them is a double count.
     outputTokens: completion ?? 0,
     cacheReadTokens: cached,
-    // Caching is automatic here and carries no write surcharge, so there is nothing to report.
-    cacheWriteTokens: 0,
+    cacheWriteTokens: written,
   };
 }
 
@@ -108,15 +158,24 @@ export function parseChatCompletion(raw: unknown, provider: string): ChatAnswer
   // `"refusal": ""` beside a real answer, and that body must not refuse here and answer streamed.
   const declined = message['refusal'];
   const refusal = typeof declined === 'string' && declined !== '' ? declined : undefined;
-  const finish = parseFinishReason(choice['finish_reason']);
+  const read = parseToolCalls(message['tool_calls']);
+  const reading = readFinishReason(choice['finish_reason']);
+  const finish =
+    reading.kind === 'none'
+      ? undefined
+      : reading.kind === 'known'
+        ? reading.reason
+        : settledAs(read.calls);
   return {
     text: typeof message['content'] === 'string' ? message['content'] : '',
-    toolCalls: parseToolCalls(message['tool_calls'], provider),
+    toolCalls: read.calls,
+    malformed: read.malformed,
     // A refusal string is a refusal whatever the finish reason says: the field only ever appears
     // when the model declined, and `stop` beside it would read downstream as an empty answer.
     stopReason: refusal === undefined ? (finish ?? 'end_turn') : 'refusal',
     stopDetails: refusalDetails(finish, refusal),
     usage: parseOpenAiUsage(record['usage']),
+    ...(reading.kind === 'unknown' ? { unknownFinish: reading.raw } : {}),
   };
 }
 
@@ -131,41 +190,52 @@ function refusalDetails(
   return { type: 'refusal', category: 'content_filter', explanation: undefined };
 }
 
-function parseToolCalls(raw: unknown, provider: string): readonly LlmToolCall[] {
-  if (!Array.isArray(raw)) return [];
-  const calls: LlmToolCall[] = [];
+interface ReadCalls {
+  readonly calls: LlmToolCall[];
+  readonly malformed: MalformedToolCall[];
+}
+
+function parseToolCalls(raw: unknown): ReadCalls {
+  const read: ReadCalls = { calls: [], malformed: [] };
+  if (!Array.isArray(raw)) return read;
   for (const entry of raw) {
     const record = asRecord(entry);
     const fn = asRecord(record?.['function']);
     if (record === undefined || fn === undefined) continue;
     const name = typeof fn['name'] === 'string' ? fn['name'] : '';
     if (name === '') continue;
-    calls.push({
-      id: typeof record['id'] === 'string' ? record['id'] : '',
-      name,
-      input: parseArguments(fn['arguments'], name, provider),
-    });
+    const args = fn['arguments'];
+    collect(read, typeof record['id'] === 'string' ? record['id'] : '', name, args);
   }
-  return calls;
+  return read;
 }
 
-/** Arguments are a JSON string. A tool that takes none sends `''` or `'{}'`; neither is a fault. */
-function parseArguments(raw: unknown, name: string, provider: string): Record<string, unknown> {
-  if (typeof raw !== 'string' || raw.trim() === '') return {};
-  try {
-    return asRecord(JSON.parse(raw)) ?? {};
-  } catch (error) {
-    throw malformed(
-      provider,
-      `tool "${name}" returned arguments that are not JSON: ${renderThrowable(error)}`,
-    );
+/** One call, read: among the calls when its arguments parse, among the malformed when not. */
+function collect(
+  read: ReadCalls,
+  id: string,
+  name: string,
+  args: unknown,
+): LlmToolCall | undefined {
+  const raw = typeof args === 'string' ? args : '';
+  const input = parseToolArguments(raw);
+  if (input === undefined) {
+    read.malformed.push({ name, chars: raw.length });
+    return undefined;
   }
+  const call: LlmToolCall = { id, name, input };
+  read.calls.push(call);
+  return call;
 }
 
 interface PendingCall {
+  /** Where the call sorts among its turn's: the wire's `index`, else its order of arrival. */
+  readonly index: number;
   id: string;
   name: string;
   args: string;
+  /** A second NAMED fragment arrived with no index and no id: two calls, indistinguishable. */
+  unkeyed?: boolean;
 }
 
 /**
@@ -180,11 +250,14 @@ export class ChatCompletionStream {
   private text = '';
   private refusal = '';
   private stopReason: StopReason = 'end_turn';
+  private unknownFinish: string | undefined;
   private finished = false;
   private done = false;
   private usage: TokenUsage | undefined;
-  private readonly pending = new Map<number, PendingCall>();
-  private readonly toolCalls: LlmToolCall[] = [];
+  /** Every open call, in order of arrival; `byIndex` is which one a wire index currently means. */
+  private readonly pending: PendingCall[] = [];
+  private readonly byIndex = new Map<number, PendingCall>();
+  private readonly read: ReadCalls = { calls: [], malformed: [] };
   private readonly provider: string;
 
   constructor(provider: string) {
@@ -196,7 +269,7 @@ export class ChatCompletionStream {
     // The sentinel is not JSON, and parsing it is how a stream reader ends in a syntax error.
     if (frame.data.trim() === '[DONE]') {
       this.done = true;
-      return [];
+      return this.end();
     }
     const payload = this.payloadOf(frame);
     throwInBandError(payload, this.provider);
@@ -205,7 +278,34 @@ export class ChatCompletionStream {
     const choice = asRecord(Array.isArray(payload['choices']) ? payload['choices'][0] : undefined);
     if (choice === undefined) return [];
     const chunks = this.onDelta(asRecord(choice['delta']) ?? {});
-    return [...chunks, ...this.onFinish(choice['finish_reason'])];
+    this.onFinish(choice['finish_reason']);
+    return chunks;
+  }
+
+  /**
+   * The stream is over: the calls a finished turn made, whole, in index order. Called by the
+   * provider when the socket closes, and by `[DONE]` — whichever comes first; the second is empty.
+   *
+   * Here, and not when the finish reason arrives: this format has no per-call stop event, and
+   * nothing in it orders the finish reason against the last argument fragment — a call read at the
+   * reason is read half way whenever a gateway sends the reason first. A turn with no finish
+   * reason drains nothing: its fragments stay open, and `isComplete()` refuses the stream.
+   */
+  end(): readonly StreamChunk[] {
+    if (!this.finished) return [];
+    const chunks: StreamChunk[] = [];
+    for (const pending of this.pending.splice(0).sort((a, b) => a.index - b.index)) {
+      if (pending.name === '') continue;
+      if (pending.unkeyed === true) {
+        // Deliberate: merged arguments are never parsed, even when they happen to be JSON.
+        this.read.malformed.push({ name: pending.name, chars: pending.args.length, unkeyed: true });
+        continue;
+      }
+      const call = collect(this.read, pending.id, pending.name, pending.args);
+      if (call !== undefined) chunks.push({ type: 'tool-call', call });
+    }
+    this.byIndex.clear();
+    return chunks;
   }
 
   /** True once the answer is accounted for. False means the connection died mid-answer. */
@@ -223,20 +323,29 @@ export class ChatCompletionStream {
     // half a JSON object, and would report `end_turn` for a turn that stopped to call one. So the
     // stream is refused exactly as the Anthropic half refuses a missing `message_stop`
     // (`provider.ts`), and `openai-provider.ts`'s existing truncation guard is what raises it.
-    return this.finished || (this.done && this.pending.size === 0);
+    return this.finished || (this.done && this.pending.length === 0);
   }
 
   /** What the stream accumulated. `cost` is applied by the provider, which owns prices. */
   state(): ChatAnswer {
+    // Idempotent, so a reader that never called `end()` still sees a finished turn's calls.
+    this.end();
     const details = this.refusalDetails();
     return {
       text: this.text,
-      toolCalls: [...this.toolCalls],
+      toolCalls: [...this.read.calls],
+      malformed: [...this.read.malformed],
       // A refusal that arrived as a `refusal` delta finishes with `stop`, so the reason alone would
       // read as a complete answer that happens to be empty.
-      stopReason: details === undefined ? this.stopReason : 'refusal',
+      stopReason:
+        details !== undefined
+          ? 'refusal'
+          : this.unknownFinish === undefined
+            ? this.stopReason
+            : settledAs(this.read.calls),
       stopDetails: details,
       usage: this.usage,
+      ...(this.unknownFinish === undefined ? {} : { unknownFinish: this.unknownFinish }),
     };
   }
 
@@ -270,54 +379,60 @@ export class ChatCompletionStream {
   }
 
   /**
-   * Merge one chunk's tool-call fragments into the calls they belong to. `index` is the only key —
+   * Merge one chunk's tool-call fragments into the calls they belong to. `index` is the key —
    * `id` and `name` arrive on the first fragment and are absent from every later one, so appending
    * by array position instead would build one call per chunk and lose every argument but the last.
+   *
+   * It is not the WHOLE key. A gateway translating another vendor's stream may number every call
+   * of a turn `0` (or send no index) and tell them apart by id alone; merged by index, two
+   * well-formed calls became one string — `{…}{…}` — that is not JSON. So a fragment carrying an id
+   * that is not the open call's starts a new call. An id repeated on every fragment, or absent
+   * from all but the first, is still one call.
    */
   private accumulate(raw: unknown): void {
     if (!Array.isArray(raw)) return;
     for (const entry of raw) {
       const record = asRecord(entry);
       if (record === undefined) continue;
-      const index = numberOf(record['index']) ?? 0;
-      const call = this.pending.get(index) ?? { id: '', name: '', args: '' };
-      const id = record['id'];
-      if (typeof id === 'string' && id !== '') call.id = id;
+      const index = numberOf(record['index']);
+      const rawId = record['id'];
+      const id = typeof rawId === 'string' && rawId !== '' ? rawId : undefined;
+      let call = index === undefined ? this.pending.at(-1) : this.byIndex.get(index);
+      if (call === undefined || (id !== undefined && call.id !== '' && call.id !== id)) {
+        call = { index: index ?? this.pending.length, id: '', name: '', args: '' };
+        this.pending.push(call);
+      }
+      if (index !== undefined) this.byIndex.set(index, call);
+      if (id !== undefined) call.id = id;
       const fn = asRecord(record['function']);
       const name = fn?.['name'];
+      // No index, no id, and a tool NAMED again after arguments already arrived: a second call
+      // this stream gives no way to tell from the first. A name split across frames arrives
+      // before any argument, so that legal case is not this one.
+      if (
+        index === undefined &&
+        id === undefined &&
+        call.args !== '' &&
+        name !== undefined &&
+        name !== ''
+      ) {
+        call.unkeyed = true;
+      }
       // Concatenated, not assigned: a server that splits the name across two frames is rare and
       // legal, and assigning would keep only the tail.
       if (typeof name === 'string') call.name += name;
       const args = fn?.['arguments'];
       if (typeof args === 'string') call.args += args;
-      this.pending.set(index, call);
     }
   }
 
-  /**
-   * The finish reason closes the turn, and it is the only close this format has: there is no
-   * per-block stop event, so pending tool calls are emitted here — whole, in index order, exactly
-   * as the Anthropic path emits them at `content_block_stop`. A fragment is never a call.
-   */
-  private onFinish(raw: unknown): readonly StreamChunk[] {
-    const reason = parseFinishReason(raw);
-    if (reason === undefined) return [];
-    this.stopReason = reason;
+  /** The finish reason closes the TURN. The calls are read by `end()`, when the stream is over. */
+  private onFinish(raw: unknown): void {
+    const reading = readFinishReason(raw);
+    if (reading.kind === 'none') return;
+    if (reading.kind === 'known') this.stopReason = reading.reason;
+    else this.unknownFinish = reading.raw;
     this.finished = true;
-    const chunks: StreamChunk[] = [];
-    for (const index of [...this.pending.keys()].sort((a, b) => a - b)) {
-      const pending = this.pending.get(index);
-      if (pending === undefined || pending.name === '') continue;
-      const call: LlmToolCall = {
-        id: pending.id,
-        name: pending.name,
-        input: parseArguments(pending.args, pending.name, this.provider),
-      };
-      this.toolCalls.push(call);
-      chunks.push({ type: 'tool-call', call });
-    }
-    this.pending.clear();
-    return chunks;
   }
 
   private payloadOf(frame: SseFrame): Record<string, unknown> {

package/src/prompt-cache-blocks.ts

@@ -0,0 +1,114 @@
+// Single responsibility: the Anthropic Messages wire's half of prompt caching — `system` as text
+// blocks, and `cache_control` on the blocks ./prompt-cache's `blocks` rule names. Pure, so the body
+// a test asserts is the body the socket gets.
+
+import type { SystemPrompt } from './prompt-cache';
+import { CACHE_MARK, systemParts } from './prompt-cache';
+import type { AiMessage, GenerateRequest } from './provider';
+
+type Marked<T> = T & { readonly cache_control?: typeof CACHE_MARK };
+type TextBlock = Marked<{ readonly type: 'text'; readonly text: string }>;
+type WireMessage = { readonly role: AiMessage['role']; readonly content: unknown };
+
+/** The vendor's ceiling on breakpoints in one request; a fifth is a 400. */
+const MAX_BREAKPOINTS = 4;
+
+/** An empty or whitespace-only text block cannot carry a mark (and is a 400 with one). */
+const blank = (text: string): boolean => text.trim() === '';
+
+export interface AnthropicPrompt {
+  readonly system: string | readonly TextBlock[] | undefined;
+  readonly messages: readonly WireMessage[];
+}
+
+/**
+ * `system` and `messages` as the wire takes them. Unmarked, a string system stays the string every
+ * existing request sent and the messages pass through untouched.
+ *
+ * Marked, at most three breakpoints, spent in this order: the transcript's TAIL (what the next
+ * request reads back), the stable system block (what other runs share), then the message before
+ * the tail (a second start for the 20-block lookback). Marks the caller already placed — a raw
+ * block or tool carrying its own `cache_control` — count against the four first, so this never
+ * turns a legal request into a 400; ours are the ones dropped.
+ */
+export function anthropicPrompt(request: GenerateRequest, marked: boolean): AnthropicPrompt {
+  const { messages } = request;
+  if (!marked) {
+    return { system: systemOf(request.system, false), messages: messages.map(plain) };
+  }
+  let left = MAX_BREAKPOINTS - placedBy(request);
+  const take = (wanted: boolean): boolean => {
+    if (!wanted || left <= 0) return false;
+    left -= 1;
+    return true;
+  };
+  const tail = messages.length - 1;
+  const markTail = take(tail >= 0 && markableAt(messages[tail]) !== undefined);
+  const markSystem = take(!blank(systemParts(request.system).stable));
+  const markPrevious = take(tail >= 1 && markableAt(messages[tail - 1]) !== undefined);
+  return {
+    system: systemOf(request.system, markSystem),
+    messages: messages.map((message, index) =>
+      (index === tail && markTail) || (index === tail - 1 && markPrevious)
+        ? { role: message.role, content: markedContent(message.content) }
+        : plain(message),
+    ),
+  };
+}
+
+const plain = (message: AiMessage): WireMessage => ({
+  role: message.role,
+  content: message.content,
+});
+
+/** The stable block first and the only one marked; an empty part is dropped, never sent. */
+function systemOf(
+  system: SystemPrompt | undefined,
+  marked: boolean,
+): string | readonly TextBlock[] | undefined {
+  if (system === undefined) return undefined;
+  if (typeof system === 'string' && !marked) return system;
+  const { stable, run } = systemParts(system);
+  const blocks: TextBlock[] = [];
+  if (stable !== '') {
+    blocks.push({ type: 'text', text: stable, ...(marked ? { cache_control: CACHE_MARK } : {}) });
+  }
+  if (run !== '') blocks.push({ type: 'text', text: run });
+  return blocks.length === 0 ? undefined : blocks;
+}
+
+/**
+ * Where one message's mark goes: its LAST block that is not blank text, so the mark moves back
+ * past a trailing empty block rather than landing on it. `undefined` when no block can carry one.
+ */
+function markableAt(message: AiMessage | undefined): number | undefined {
+  if (message === undefined) return undefined;
+  const { content } = message;
+  if (typeof content === 'string') return blank(content) ? undefined : 0;
+  for (let index = content.length - 1; index >= 0; index -= 1) {
+    const block = content[index];
+    if (block !== undefined && !(block.type === 'text' && blank(block.text))) return index;
+  }
+  return undefined;
+}
+
+function markedContent(content: AiMessage['content']): unknown {
+  if (typeof content === 'string') {
+    return [{ type: 'text', text: content, cache_control: CACHE_MARK }];
+  }
+  const at = markableAt({ role: 'user', content });
+  return content.map((block, index) =>
+    index === at ? { ...block, cache_control: CACHE_MARK } : block,
+  );
+}
+
+/** Breakpoints the caller placed itself: the types do not offer the field, a cast still sends it. */
+function placedBy(request: GenerateRequest): number {
+  const carries = (value: unknown): boolean =>
+    typeof value === 'object' && value !== null && Object.hasOwn(value, 'cache_control');
+  let count = (request.tools ?? []).filter(carries).length;
+  for (const { content } of request.messages) {
+    if (typeof content !== 'string') count += content.filter(carries).length;
+  }
+  return count;
+}