@ultimat3/ai 2.0.0 → 4.0.0

package/src/openai-provider.ts

@@ -11,6 +11,7 @@ import type { Secret } from '@ultimat3/core';
 import { isSecret, revealSecret } from '@ultimat3/core';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
+import type { AiFetch } from './fetch-seam';
 import type { ModelId } from './models';
 import { chatCompletionBody } from './openai-body';
 // Imported for its registration side effect: a provider that cannot price what it serves throws
@@ -66,7 +67,7 @@ export interface OpenAiProviderInput {
    */
   readonly name?: string;
   /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
-  readonly fetch?: typeof fetch;
+  readonly fetch?: AiFetch;
 }
 
 /**
@@ -114,14 +115,22 @@ class OpenAiProvider implements Provider {
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     if (requiresStreaming(request)) return this.assemble(request);
     const model = this.modelOf(request);
-    const response = await this.send(chatCompletionBody({ request, model, stream: false }), false);
+    const response = await this.send(
+      chatCompletionBody({ request, model, stream: false }),
+      false,
+      request.signal,
+    );
     const answer = parseChatCompletion((await response.json()) as unknown, this.name);
     return this.result(request, model, answer);
   }
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = this.modelOf(request);
-    const response = await this.send(chatCompletionBody({ request, model, stream: true }), true);
+    const response = await this.send(
+      chatCompletionBody({ request, model, stream: true }),
+      true,
+      request.signal,
+    );
     if (response.body === null) {
       throw new AiTransportError({
         provider: this.name,
@@ -130,7 +139,7 @@ class OpenAiProvider implements Provider {
       });
     }
     const completion = new ChatCompletionStream(this.name);
-    for await (const frame of readSse(response.body)) {
+    for await (const frame of readSse(response.body, this.name)) {
       for (const chunk of completion.push(frame)) yield chunk;
     }
     // A connection cut mid-answer must fail, not resolve: partial text reads as a complete answer,
@@ -183,9 +192,13 @@ class OpenAiProvider implements Provider {
    * its status, because the gateway decides whether to retry from that status and a body parsed as
    * if it were a message would read as an empty, successful answer.
    */
-  private async send(body: Record<string, unknown>, streaming: boolean): Promise<Response> {
+  private async send(
+    body: Record<string, unknown>,
+    streaming: boolean,
+    signal: AbortSignal | undefined,
+  ): Promise<Response> {
     const apiKey = this.apiKey();
-    const doFetch = this.config.fetch ?? fetch;
+    const doFetch: AiFetch = this.config.fetch ?? fetch;
     const response = await doFetch(this.url(), {
       method: 'POST',
       headers: {
@@ -199,6 +212,8 @@ class OpenAiProvider implements Provider {
         ...this.config.headers,
       },
       body: JSON.stringify(body),
+      // Attached only when the caller has one — same rule, same reason, as the Anthropic half.
+      ...(signal === undefined ? {} : { signal }),
     });
     if (!response.ok) {
       throw new AiTransportError({

package/src/openai-wire.ts

@@ -24,34 +24,46 @@ export interface ChatAnswer {
   readonly usage: TokenUsage | undefined;
 }
 
-const FINISH_REASONS: Readonly<Record<string, StopReason>> = {
-  stop: 'end_turn',
-  length: 'max_tokens',
-  tool_calls: 'tool_use',
-  // The legacy name for the same event; LiteLLM and older self-hosted servers still send it.
-  function_call: 'tool_use',
-  content_filter: 'refusal',
-};
+// A `Map`, not an object literal: `raw` is the PROVIDER's string on every read, and
+// `FINISH_REASONS['constructor']` on an object answers the `Object` FUNCTION — which
+// `parseFinishReason` returned as a `StopReason`, and which the stream reader below then treated
+// as a finish, so `isComplete()` answered true for a stream that never finished. Same fix core
+// made in `error-retry.ts` for the same shape.
+const FINISH_REASONS: ReadonlyMap<string, StopReason> = new Map(
+  Object.entries({
+    stop: 'end_turn',
+    length: 'max_tokens',
+    tool_calls: 'tool_use',
+    // The legacy name for the same event; LiteLLM and older self-hosted servers still send it.
+    function_call: 'tool_use',
+    content_filter: 'refusal',
+  } as const),
+);
 
 /**
  * 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.
  */
-const ERROR_STATUS: Readonly<Record<string, number>> = {
-  invalid_request_error: 400,
-  authentication_error: 401,
-  permission_error: 403,
-  not_found_error: 404,
-  rate_limit_exceeded: 429,
-  insufficient_quota: 429,
-  server_error: 500,
-  api_error: 500,
-  overloaded_error: 503,
-};
+// A `Map`, for the reason `FINISH_REASONS` above is one: `type` is the provider's string, and a
+// function where `AiTransportError.status` is declared `number | undefined` makes `isRetryable`
+// answer false for a 429-class frame and interpolates JS source into the operator-facing `cause`.
+const ERROR_STATUS: ReadonlyMap<string, number> = new Map(
+  Object.entries({
+    invalid_request_error: 400,
+    authentication_error: 401,
+    permission_error: 403,
+    not_found_error: 404,
+    rate_limit_exceeded: 429,
+    insufficient_quota: 429,
+    server_error: 500,
+    api_error: 500,
+    overloaded_error: 503,
+  }),
+);
 
 /** A finish reason this format knows, or `undefined` for `null` — which means "still going". */
 export function parseFinishReason(raw: unknown): StopReason | undefined {
-  return typeof raw === 'string' ? FINISH_REASONS[raw] : undefined;
+  return typeof raw === 'string' ? FINISH_REASONS.get(raw) : undefined;
 }
 
 /**
@@ -64,10 +76,10 @@ export function parseFinishReason(raw: unknown): StopReason | undefined {
 export function parseOpenAiUsage(raw: unknown): TokenUsage | undefined {
   const record = asRecord(raw);
   if (record === undefined) return undefined;
-  const prompt = numberOf(record['prompt_tokens']);
-  const completion = numberOf(record['completion_tokens']);
+  const prompt = countOf(record['prompt_tokens']);
+  const completion = countOf(record['completion_tokens']);
   if (prompt === undefined && completion === undefined) return undefined;
-  const cached = numberOf(asRecord(record['prompt_tokens_details'])?.['cached_tokens']) ?? 0;
+  const cached = countOf(asRecord(record['prompt_tokens_details'])?.['cached_tokens']) ?? 0;
   return {
     inputTokens: Math.max((prompt ?? 0) - cached, 0),
     // `completion_tokens` already contains `reasoning_tokens`; adding them is a double count.
@@ -194,7 +206,17 @@ export class ChatCompletionStream {
     // Either sentinel counts. `[DONE]` is the format's own end marker, but plenty of servers in
     // the family close the socket straight after the finish-reason chunk — and a finish reason IS
     // the model saying why it stopped, which is the fact a truncated stream cannot produce.
-    return this.done || this.finished;
+    //
+    // One exception, and it is REFUSAL rather than a flush: `[DONE]` while tool-call fragments are
+    // still open. This format has no per-call stop event, so the finish reason is the only thing
+    // that ever closes a call and `onFinish` is the only drain of `pending` — which means `[DONE]`
+    // alone cannot tell "the model finished asking" from "the connection died mid-arguments".
+    // Reporting complete discarded a whole tool call and answered an empty, successful `end_turn`;
+    // emitting the fragments anyway would run a tool's side effects from arguments that may be
+    // 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);
   }
 
   /** What the stream accumulated. `cost` is applied by the provider, which owns prices. */
@@ -320,7 +342,8 @@ function throwInBandError(payload: Record<string, unknown>, provider: string): v
   const message = typeof error['message'] === 'string' ? error['message'] : type;
   throw new AiTransportError({
     provider,
-    status: ERROR_STATUS[type] ?? (code === undefined ? undefined : ERROR_STATUS[code]) ?? 500,
+    status:
+      ERROR_STATUS.get(type) ?? (code === undefined ? undefined : ERROR_STATUS.get(code)) ?? 500,
     detail: message,
   });
 }
@@ -337,3 +360,14 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 function numberOf(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+
+/**
+ * A token count, floored at zero. Usage is the PROVIDER's number and a proxy in front of one can
+ * send anything: a negative count becomes a negative `cost`, and `MemoryBudgetStore.add` takes a
+ * negative debit as a credit deliberately (releasing an unspent reservation IS one) — so an
+ * unclamped `-1` here does not under-report spend, it TOPS THE LEDGER UP. Twin of `wire.ts`'s.
+ */
+function countOf(value: unknown): number | undefined {
+  const count = numberOf(value);
+  return count === undefined ? undefined : Math.max(0, count);
+}

package/src/prompt.ts

@@ -120,7 +120,12 @@ const PLACEHOLDER = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
 function render(template: string, vars: PromptVars, ref: string): string {
   const missing: string[] = [];
   const out = template.replace(PLACEHOLDER, (_match, name: string) => {
-    const value = vars[name];
+    // `Object.hasOwn`, never `vars[name] === undefined`: a plain object inherits `constructor`,
+    // `toString` and `valueOf`, so `{{constructor}}` in a template rendered JS SOURCE into the
+    // prompt instead of raising the unfilled-slot error this file promises — and that source was
+    // then hashed into the semantic cache key and paid for at the input rate. The discriminator
+    // `@ultimat3/flags`' `subject.ts` already uses, for the same reason.
+    const value = Object.hasOwn(vars, name) ? vars[name] : undefined;
     if (value === undefined) {
       missing.push(name);
       return '';

package/src/provider.ts

@@ -6,6 +6,7 @@
 import type { Money } from '@ultimat3/money';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiTransportError } from './errors';
+import type { AiFetch } from './fetch-seam';
 import type { Effort, ModelId, ThinkingMode } from './models';
 import { ANTHROPIC_MODEL_IDS, DEFAULT_MODEL, modelIds, modelSpec, reasoningBody } from './models';
 import { readSse } from './sse';
@@ -73,6 +74,15 @@ export interface GenerateRequest {
   readonly thinking?: ThinkingMode;
   readonly tools?: readonly LlmTool[];
   readonly stopSequences?: readonly string[];
+  /**
+   * The caller's abort signal, forwarded to the socket by every provider in this package.
+   *
+   * Deliberately absent from `cacheKeyFor` and from every estimate: it says whether a request was
+   * ABANDONED, never what it asked for, so two calls that differ only in it are the same call and
+   * must share a cache entry. Omitted means the call runs to completion — there is no ambient
+   * default, because a timeout the caller did not ask for is a truncated answer nothing reports.
+   */
+  readonly signal?: AbortSignal;
 }
 
 export interface TokenUsage {
@@ -171,7 +181,7 @@ export interface AnthropicProviderInput {
   readonly apiKey?: string;
   readonly baseUrl?: string;
   /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
-  readonly fetch?: typeof fetch;
+  readonly fetch?: AiFetch;
 }
 
 const ANTHROPIC_VERSION = '2023-06-01';
@@ -216,7 +226,7 @@ export class AnthropicProvider implements Provider {
    */
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     if (requiresStreaming(request)) return this.assemble(request);
-    const response = await this.send({ ...this.body(request), stream: false });
+    const response = await this.send({ ...this.body(request), stream: false }, request.signal);
     const raw = (await response.json()) as Record<string, unknown>;
     return parseMessage(request.model ?? DEFAULT_MODEL, raw);
   }
@@ -239,7 +249,7 @@ export class AnthropicProvider implements Provider {
    */
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = request.model ?? DEFAULT_MODEL;
-    const response = await this.send({ ...this.body(request), stream: true });
+    const response = await this.send({ ...this.body(request), stream: true }, request.signal);
     if (response.body === null) {
       throw new AiTransportError({
         provider: this.name,
@@ -248,7 +258,7 @@ export class AnthropicProvider implements Provider {
       });
     }
     const message = new MessageStream();
-    for await (const frame of readSse(response.body)) {
+    for await (const frame of readSse(response.body, this.name)) {
       for (const chunk of message.push(frame)) yield chunk;
     }
     // A connection cut mid-answer must fail, not resolve: the partial text reads as a complete
@@ -286,12 +296,15 @@ export class AnthropicProvider implements Provider {
    * carrying its status, because the gateway decides whether to retry from that status and a
    * body parsed as if it were a message would read as an empty, successful answer.
    */
-  private async send(body: Record<string, unknown>): Promise<Response> {
+  private async send(
+    body: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+  ): Promise<Response> {
     const apiKey = this.config.apiKey ?? Bun.env[API_KEY_ENV];
     if (apiKey === undefined || apiKey === '') {
       throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
     }
-    const doFetch = this.config.fetch ?? fetch;
+    const doFetch: AiFetch = this.config.fetch ?? fetch;
     const url = `${this.config.baseUrl ?? 'https://api.anthropic.com'}/v1/messages`;
     const response = await doFetch(url, {
       method: 'POST',
@@ -302,6 +315,9 @@ export class AnthropicProvider implements Provider {
         accept: body['stream'] === true ? 'text/event-stream' : 'application/json',
       },
       body: JSON.stringify(body),
+      // Attached only when the caller has one: `exactOptionalPropertyTypes`, and an explicit
+      // `signal: undefined` is a different value to some fetch implementations.
+      ...(signal === undefined ? {} : { signal }),
     });
     if (!response.ok) {
       throw new AiTransportError({
@@ -393,7 +409,7 @@ export class EchoProvider implements Provider {
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     const model = request.model ?? DEFAULT_MODEL;
     const prompt = lastUserMessage(request.messages);
-    const text = this.config.replies?.[prompt] ?? this.config.fallback?.(prompt) ?? prompt;
+    const text = this.fixedReply(prompt) ?? this.config.fallback?.(prompt) ?? prompt;
     const usage: TokenUsage = {
       inputTokens: this.config.tokensPerCall ?? estimateTokens(request),
       outputTokens: estimateTextTokens(text),
@@ -411,6 +427,17 @@ export class EchoProvider implements Provider {
     };
   }
 
+  /**
+   * The fixture reply for this prompt. `Object.hasOwn`, never `replies?.[prompt]`: the key is
+   * MESSAGE TEXT, so a prompt of `toString` read a function off the prototype chain and returned
+   * it as the model's answer — a double that answers with JS source is worse than one that cannot.
+   */
+  private fixedReply(prompt: string): string | undefined {
+    const { replies } = this.config;
+    if (replies === undefined || !Object.hasOwn(replies, prompt)) return undefined;
+    return replies[prompt];
+  }
+
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const result = await this.generate(request);
     // One word per chunk: enough to exercise a consumer's assembly logic.

package/src/rag.ts

@@ -31,9 +31,12 @@ export interface ChunkInput {
  * boundary lands at a meaning boundary whenever one is available within the budget.
  */
 export function chunk(input: ChunkInput): readonly Chunk[] {
-  const size = input.size ?? 512;
+  // Floored at one token: `size: 0` makes every comparison below meaningless and the wrap's cut
+  // point zero-width, which is a loop that never advances rather than a chunker that produces
+  // nothing. A budget under one token is not a budget.
+  const size = Math.max(1, Math.floor(input.size ?? 512));
   const overlap = Math.min(input.overlap ?? 64, size - 1);
-  const units = splitUnits(input.text);
+  const units = splitUnits(input.text, size);
   const chunks: Chunk[] = [];
   let buffer: string[] = [];
   let tokens = 0;
@@ -49,10 +52,14 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
         metadata: { source: input.id, ...(input.metadata ?? {}) },
       });
     }
-    // Carry the tail forward as the overlap for the next chunk.
+    // Carry the tail forward as the overlap for the next chunk — at most every unit BUT THE
+    // FIRST. Walking back to index 0 re-seeded the next buffer with everything just flushed, so
+    // a single unit whose own size exceeds `overlap` became the whole of the next chunk, and the
+    // next, and the next: a ~1,000-token document indexed as nine chunks of the same sentence.
+    // The wrap above bounds a unit; this bounds the loop, and both are needed.
     const carried: string[] = [];
     let carriedTokens = 0;
-    for (let i = buffer.length - 1; i >= 0 && carriedTokens < overlap; i -= 1) {
+    for (let i = buffer.length - 1; i >= 1 && carriedTokens < overlap; i -= 1) {
       const unit = buffer[i] ?? '';
       carried.unshift(unit);
       carriedTokens += estimateChunkTokens(unit);
@@ -72,7 +79,7 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
   return chunks;
 }
 
-function splitUnits(text: string): readonly string[] {
+function splitUnits(text: string, size: number): readonly string[] {
   const units: string[] = [];
   for (const paragraph of text.split(/\n{2,}/)) {
     const trimmed = paragraph.trim();
@@ -81,12 +88,65 @@ function splitUnits(text: string): readonly string[] {
     const sentences = trimmed.match(/[^.!?]+[.!?]*\s*/g) ?? [trimmed];
     for (const sentence of sentences) {
       const s = sentence.trim();
-      if (s !== '') units.push(s);
+      if (s !== '') units.push(...hardWrap(s, size));
     }
   }
   return units;
 }
 
+/**
+ * The third split the header promises, and the one that was missing: a unit no larger than the
+ * budget. Neither split above can guarantee it — a base64 blob, a minified line, a CJK paragraph
+ * this splitter's `[.!?]` alphabet cannot see and a legal 400-word sentence all survive both — and
+ * an oversized unit is a chunk the size check can never flush, because the check only fires when
+ * something is ALREADY in the buffer.
+ *
+ * Word boundaries first, so a chunk edge still lands at a meaning boundary when one exists within
+ * the budget; a run with no boundary in it is cut mid-word, because the alternative is no boundary
+ * at all.
+ */
+function hardWrap(unit: string, size: number): readonly string[] {
+  if (estimateChunkTokens(unit) <= size) return [unit];
+  const pieces: string[] = [];
+  let piece = '';
+  const flushPiece = (): void => {
+    if (piece !== '') pieces.push(piece);
+    piece = '';
+  };
+  for (const word of unit.split(/\s+/)) {
+    if (word === '') continue;
+    const candidate = piece === '' ? word : `${piece} ${word}`;
+    if (estimateChunkTokens(candidate) <= size) {
+      piece = candidate;
+      continue;
+    }
+    flushPiece();
+    if (estimateChunkTokens(word) <= size) {
+      piece = word;
+      continue;
+    }
+    pieces.push(...cutToBudget(word, size));
+  }
+  flushPiece();
+  return pieces;
+}
+
+/**
+ * One word longer than the whole budget, cut into pieces that fit. The estimator is linear in
+ * length, so the ratio over what is left gives the cut point directly — `Math.max(1, …)` is what
+ * keeps a pathological ratio from producing a zero-width cut and a loop that never advances.
+ */
+function cutToBudget(run: string, size: number): readonly string[] {
+  const pieces: string[] = [];
+  let rest = run;
+  while (rest !== '') {
+    const fit = Math.max(1, Math.floor((rest.length * size) / estimateChunkTokens(rest)));
+    pieces.push(rest.slice(0, fit));
+    rest = rest.slice(fit);
+  }
+  return pieces;
+}
+
 /** Index a document: chunk, embed, upsert. One call so no step is skipped by accident. */
 export async function indexDocument(input: {
   readonly store: VectorStore;

package/src/remote-embedder.ts

@@ -10,6 +10,7 @@ import { readWithinLimit } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { normalize } from './embeddings';
 import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
+import type { AiFetch } from './fetch-seam';
 
 const API_KEY_ENV = 'EMBEDDINGS_API_KEY';
 const DEFAULT_BASE_URL = 'https://api.voyageai.com/v1';
@@ -44,7 +45,7 @@ export interface RemoteEmbedderInput {
   /** Bytes this process will hold of one response. Defaults to 32 MiB. */
   readonly maxResponseBytes?: number;
   /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
-  readonly fetch?: typeof fetch;
+  readonly fetch?: AiFetch;
 }
 
 export class RemoteEmbedder implements Embedder {
@@ -77,7 +78,7 @@ export class RemoteEmbedder implements Embedder {
     if (apiKey === undefined || apiKey === '') {
       throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
     }
-    const doFetch = this.config.fetch ?? fetch;
+    const doFetch: AiFetch = this.config.fetch ?? fetch;
     const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const url = `${this.config.baseUrl ?? DEFAULT_BASE_URL}/embeddings`;
     let response: Response;

package/src/runtime.ts

@@ -9,6 +9,7 @@
 
 import type { SemanticCache } from '@ultimat3/cache';
 import { createMemorySemanticCache } from '@ultimat3/cache';
+import { cachedFormatter, MAX_CACHED_FORMATTERS } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { HashEmbedder } from './embeddings';
 import { AiGatewayMissingError } from './errors';
@@ -85,18 +86,31 @@ export function aiRedactor(): Redactor {
   return runtime?.redact ?? noRedaction;
 }
 
+/**
+ * How many scopes hold a live cache instance at once. Core's bound, not a second one — the name
+ * `MAX_CACHED_FORMATTERS` is about `cachedFormatter`'s first caller, never about its contract,
+ * and a second FIFO map written here would be two answers to one question (axiom 1).
+ */
+export const MAX_SEMANTIC_CACHE_SCOPES = MAX_CACHED_FORMATTERS;
+
 /**
  * The cache for one scope. Scopes are separate CACHE INSTANCES, never a filter over a shared
  * one: cosine similarity has no notion of a tenant, so two tenants asking near-identical
  * questions of a shared cache is one tenant reading the other's answer. Partitioning is the
  * only thing that makes that structurally impossible.
+ *
+ * BOUNDED, and that is new with `llm()`'s actor-derived default scope: the default was the single
+ * string `'global'`, so this map held one entry no matter how many callers there were, and the
+ * narrowest-key default makes it one entry per ACTOR in a process that never restarts. Eviction
+ * costs nothing but a rebuild — a `SemanticCache` is a handle, so the durable ones (pgvector) lose
+ * no entries at all and the memory one loses a cache.
  */
 export function semanticCacheFor(scope: string): SemanticCache {
-  const existing = caches.get(scope);
-  if (existing !== undefined) return existing;
-  const created = runtime?.semanticCache(scope) ?? createMemorySemanticCache();
-  caches.set(scope, created);
-  return created;
+  return cachedFormatter(
+    caches,
+    scope,
+    () => runtime?.semanticCache(scope) ?? createMemorySemanticCache(),
+  );
 }
 
 /** Test-only reset. Module-level state otherwise leaks between test files. */

package/src/sse.ts

@@ -5,6 +5,21 @@
 // stream is a boundary search and a field split, and the only interesting property — that a
 // frame may arrive split at any byte offset — is exactly what a library would hide.
 
+import { AiTransportError } from './errors';
+
+/**
+ * The most one unterminated frame may buffer. A peer that sends a body with no frame boundary in
+ * it — an HTML error page, a proxy answering on the model's port, a hung gateway — grows `buffer`
+ * without limit, and no read deadline interrupts it because every individual read SUCCEEDS. Coded
+ * failure > OOM, the same call `@ultimat3/mail`'s `createReplyParser` makes for the same shape.
+ *
+ * Counted in UTF-16 code units rather than bytes: `buffer` holds decoded text, and a decoded unit
+ * is never more than one byte of input, so the cap is conservative in the direction that matters.
+ * A megabyte is orders of magnitude above the largest single delta any provider in this package
+ * sends, so a legitimate stream can never reach it.
+ */
+export const MAX_FRAME_CHARS = 1024 * 1024;
+
 export interface SseFrame {
   /** The `event:` field, or `message` when the frame omits one — the spec's default. */
   readonly event: string;
@@ -57,7 +72,12 @@ function frameOf(block: string): SseFrame | undefined {
  * a stream cut mid-message must fail loudly at the consumer that parses it, and dropping the
  * tail silently would turn a truncated answer into a complete-looking one.
  */
-export async function* readSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseFrame> {
+export async function* readSse(
+  body: ReadableStream<Uint8Array>,
+  /** Named, never defaulted: the cap below fails as a transport error, and a transport error the
+   * caller reads has to say which endpoint it is about. */
+  provider: string,
+): AsyncGenerator<SseFrame> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = '';
@@ -66,6 +86,7 @@ export async function* readSse(body: ReadableStream<Uint8Array>): AsyncGenerator
       const { done, value } = await reader.read();
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
+      guard(buffer, provider);
       const decoded = decodeSse(buffer);
       buffer = decoded.rest;
       for (const frame of decoded.frames) yield frame;
@@ -79,3 +100,13 @@ export async function* readSse(body: ReadableStream<Uint8Array>): AsyncGenerator
     await reader.cancel().catch(() => undefined);
   }
 }
+
+function guard(buffer: string, provider: string): void {
+  if (buffer.length <= MAX_FRAME_CHARS) return;
+  throw new AiTransportError({
+    provider,
+    detail:
+      `the stream sent more than ${MAX_FRAME_CHARS} characters without completing one SSE ` +
+      'frame — the endpoint is answering with something that is not an event stream',
+  });
+}