@kitn.ai/ui 0.25.2 → 0.26.0

package/src/wire/encode-probe.ts

@@ -0,0 +1,214 @@
+// The encoders' diagnostic ledger: what went in, what came out, what did not.
+//
+// SEPARATE FROM encode.ts on purpose, and the reason is a guard rather than
+// tidiness. `lint:silent-drops` holds every function in `src/wire/` that
+// discriminates a `MessagePart` responsible for all six variants, and it is
+// right to. Nothing in this file discriminates one: every entry point takes the
+// variant as a STRING, read at the call site out of a branch that had already
+// discriminated it. So instrumenting the drops cannot introduce a new switch to
+// go stale when a seventh variant lands, and the parts that reach `dropped()`
+// are typed `unknown` so they cannot be inspected here even by accident.
+//
+// ZERO COST WITH NO SUBSCRIBER. The encoders build a probe only inside a
+// `wireDiagnosticsActive()` branch and reach it through `probe?.`, so with
+// nobody listening the whole ledger is one symbol read per encode and a handful
+// of skipped optional calls.
+//
+// SSR: no window, no globals at module scope. The TextEncoder is built on first
+// use, the same rule `read.ts` follows.
+import {
+  emitWireDiagnostic,
+  wirePayloadActive,
+  withPayload,
+  type EncodeAttachmentReport,
+} from './diagnostics';
+
+/** Built on first use and cached -- never at module scope, so this module keeps
+ *  importing cleanly in a runtime that lacks the global. Only ever reached from
+ *  inside an active-diagnostics branch. */
+let encoder: TextEncoder | undefined;
+
+/**
+ * UTF-8 byte length of the encoded body, or undefined when it cannot be one.
+ *
+ * ★ ONLY CALLED WHEN PAYLOAD CAPTURE IS ON, i.e. when the body is being
+ * materialized for a subscriber anyway. `base64Bytes` below refuses to decode a
+ * 40 MB attachment to count it, on the grounds that the diagnostic would cost
+ * more than the encode it is watching -- and stringifying the whole body to
+ * produce one number is that same mistake one level up. With payload off the
+ * field is OMITTED, which reads as "not reported" under the absence rule.
+ *
+ * Measured against the built bundle, subscribed with payload OFF, on a thread
+ * of ten 1 MB attachments whose bare encode is 4.2 ms: ungated the
+ * instrumentation cost +36.6 ms and +0.9 MB of heap; gated it costs +5.8 ms and
+ * no measurable heap. (Upper bounds -- the box was not idle. `--expose-gc`, 15
+ * runs, `scripts/`-adjacent harness in the PR.)
+ *
+ * NOT REPLACED BY AN ESTIMATE. A number that looks like a measurement and is
+ * not is worse than an absent field, and a size threshold would make the
+ * field's presence depend on how big the body happened to be -- which is the
+ * one thing a reader would then be unable to conclude anything from.
+ *
+ * `JSON.stringify` is not total either: a circular `tool.output` or a BigInt
+ * anywhere in a host's own data throws, and a diagnostic must never be the thing
+ * that breaks an encode. That case goes absent for the same reason.
+ */
+function bodyBytes(body: unknown): number | undefined {
+  try {
+    encoder ??= new TextEncoder();
+    return encoder.encode(JSON.stringify(body)).length;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Bytes a base64 payload stands for, WITHOUT decoding it.
+ *
+ * Four base64 characters carry three bytes, less the padding. Decoding a 40 MB
+ * attachment to count it would make the diagnostic more expensive than the
+ * encode it is watching.
+ *
+ * ★ THIS IS AN O(n) SCAN AND THERE IS NO EXACT WAY AROUND IT -- about 0.43 ms
+ * per MB of attachment. THAT IS WHY ITS CALLER IS PAYLOAD-GATED (see `bytesOf`
+ * in encode.ts): the thread is re-encoded every turn, so the scan is a
+ * recurring per-turn cost rather than a one-off, and unbounded-per-turn is what
+ * fails "cheap enough to leave on". With payload off this is never called; with
+ * payload on it runs and the number is exact.
+ *
+ * THE ALTERNATIVE WAS NOT TO GUESS, and three candidates were measured before
+ * settling on gating instead:
+ *
+ *   · A charCodeAt counting loop -- 7x SLOWER on the shape that actually occurs
+ *     (a `data:` URI, no whitespace): 2.77 ms vs 0.61 ms per 1.4 MB. It avoids
+ *     a copy that a whitespace-free `.replace` never makes, because V8 returns
+ *     the original string when the pattern does not match. Strictly worse.
+ *   · Native whitespace `.test()` then O(1) arithmetic on `.length` -- exact,
+ *     and identical in time (0.60 ms), because the test is the same full scan.
+ *     No win worth the extra branch.
+ *   · Probing only a prefix for whitespace, then O(1) arithmetic -- 170x faster
+ *     (0.0036 ms) and REJECTED anyway: it assumes whitespace is periodic line
+ *     wrapping, so a payload whose only whitespace sits past the probe window
+ *     is silently OVER-counted. That is an estimate wearing a measurement's
+ *     clothes, which is the one thing a size field must never be.
+ *
+ * So the resolution is exact-but-gated rather than always-on-but-approximate. A
+ * cheaper counter is welcome; a less truthful one is not, and `base64-bytes.
+ * test.ts` pins the arithmetic against a real decode so any replacement has to
+ * prove it is the same function rather than merely a plausible one.
+ */
+export function base64Bytes(data: string): number {
+  const clean = data.replace(/\s/g, '');
+  if (clean === '') return 0;
+  const pad = clean.endsWith('==') ? 2 : clean.endsWith('=') ? 1 : 0;
+  return Math.max(0, Math.floor((clean.length * 3) / 4) - pad);
+}
+
+export interface EncodeProbe {
+  /** One part seen in the thread. `variant` is `part.type`, read at a site that
+   *  has the part in hand -- this function never looks. */
+  seen(variant: string): void;
+  /** One part that reached the wire. */
+  encoded(variant: string): void;
+  /** One part that did NOT. `part` is carried only to be published under the
+   *  payload key, and is `unknown` so it cannot be inspected here. */
+  dropped(
+    variant: string,
+    reason: string,
+    messageIndex: number,
+    partIndex: number,
+    part: unknown,
+  ): void;
+  /** One `file` part's outcome, plus the filename held back for the payload
+   *  key. Called exactly once per file part, whatever became of it. */
+  attachment(report: EncodeAttachmentReport, filename?: string): void;
+  /** Emit `encode.request`. Called once, after the body is built. */
+  finish(
+    format: 'openai' | 'anthropic',
+    threadMessages: number,
+    body: ReadonlyArray<{ role: string }>,
+  ): void;
+}
+
+/**
+ * A ledger for one encode call.
+ *
+ * Built ONLY inside an active-diagnostics branch. It holds counts and, for the
+ * payload key, filenames; it never holds message text.
+ *
+ * NO `streamId`, deliberately. An encode is not a read: it happens before there
+ * is a response to correlate to, and minting an id here would invent a
+ * relationship the kit cannot vouch for. `traceId`/`label` DO carry, because
+ * those are the app's own declaration and the app is the one layer that knows
+ * the encoded request and the read that answered it are the same turn.
+ */
+export function createEncodeProbe(opts: { traceId?: string; label?: string }): EncodeProbe {
+  const correlation = {
+    ...(opts.traceId !== undefined ? { traceId: opts.traceId } : {}),
+    ...(opts.label !== undefined ? { label: opts.label } : {}),
+  };
+  const partsIn: Record<string, number> = {};
+  const partsEncoded: Record<string, number> = {};
+  const attachments: EncodeAttachmentReport[] = [];
+  const filenames: Array<{ filename?: string }> = [];
+
+  const bump = (into: Record<string, number>, key: string) => {
+    into[key] = (into[key] ?? 0) + 1;
+  };
+
+  return {
+    seen: (variant) => bump(partsIn, variant),
+    encoded: (variant) => bump(partsEncoded, variant),
+    dropped(variant, reason, messageIndex, partIndex, part) {
+      emitWireDiagnostic({
+        type: 'encode.dropped',
+        t: Date.now(),
+        ...correlation,
+        variant,
+        count: 1,
+        messageIndex,
+        partIndex,
+        reason,
+        // The part itself, by reference and unread. This function does not know
+        // what a part is and must not: knowing would mean discriminating one.
+        ...withPayload(() => ({ part })),
+      });
+    },
+    attachment(report, filename) {
+      attachments.push(report);
+      // Positionally aligned with `attachments`, so a panel with the payload key
+      // turned on can name the file in row N without the name ever sitting
+      // beside the metadata.
+      filenames.push(filename !== undefined ? { filename } : {});
+    },
+    finish(format, threadMessages, body) {
+      const byRole: Record<string, number> = {};
+      for (const message of body) bump(byRole, message.role);
+      // Gated: measuring costs a full serialization of every inlined
+      // attachment, so it happens only when the body is already being
+      // materialized for the payload key. See `bodyBytes`.
+      const bytes = wirePayloadActive() ? bodyBytes(body) : undefined;
+      emitWireDiagnostic({
+        type: 'encode.request',
+        t: Date.now(),
+        ...correlation,
+        format,
+        threadMessages,
+        wireMessages: body.length,
+        // Stated, not omitted: zero is the answer that tells a developer the
+        // system prompt lives somewhere the kit cannot see.
+        systemMessages: byRole.system ?? 0,
+        byRole,
+        partsIn,
+        partsEncoded,
+        attachments,
+        ...(bytes !== undefined ? { bytes } : {}),
+        // The encoded body, and the filenames held back from the ledger above.
+        ...withPayload(() => ({
+          body,
+          ...(filenames.length > 0 ? { attachments: filenames } : {}),
+        })),
+      });
+    },
+  };
+}

package/src/wire/encode.ts

@@ -7,6 +7,8 @@ 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;
@@ -100,6 +102,30 @@ export interface FileEncodeOptions {
    * 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;
@@ -173,12 +199,52 @@ function encodeFilePart<T>(
   policy: UnencodableFilePolicy,
   media: MediaPolicy,
   toBlock: (file: ClassifiedFile) => WireFileResult<T>,
+  probe: EncodeProbe | undefined,
+  messageIndex: number,
 ): T | null {
   const classified = classifyAttachment(part.attachment, media);
-  if (classified.status === 'kit-side') return null;
+  // 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): null => {
-    if (policy === 'skip') 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,
@@ -189,7 +255,49 @@ function encodeFilePart<T>(
   if (classified.status === 'unencodable') return refuse(classified.reason);
 
   const shaped = toBlock(classified.file);
-  return shaped.ok ? shaped.block : refuse(shaped.reason);
+  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
@@ -434,7 +542,16 @@ export function toOpenAIMessages(
   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
@@ -455,19 +572,47 @@ export function toOpenAIMessages(
       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;
         }
-        if (part.type !== 'file') return;
-        const block = encodeFilePart(part, message.id, partIndex, filePolicy, media, openAIFileBlock);
+        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;
@@ -502,28 +647,82 @@ export function toOpenAIMessages(
       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) continue;
+        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);
+        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' && isSettled(part.tool)) pending.push(part.tool);
+      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;
 }
 
@@ -584,6 +783,12 @@ export function toAnthropicMessages(
   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 => {
@@ -592,19 +797,47 @@ export function toAnthropicMessages(
     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 });
+          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;
         }
-        if (part.type !== 'file') return;
-        const block = encodeFilePart(part, message.id, partIndex, filePolicy, media, anthropicFileBlock);
-        if (block) userBlocks.push(block);
+        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;
@@ -645,6 +878,7 @@ export function toAnthropicMessages(
           // 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': {
@@ -652,11 +886,22 @@ export function toAnthropicMessages(
           // 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)) break;
+          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,
@@ -683,6 +928,13 @@ export function toAnthropicMessages(
           // 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;
       }
     });
@@ -690,5 +942,6 @@ export function toAnthropicMessages(
     flush();
   }
 
+  probe?.finish('anthropic', messages.length, out);
   return out;
 }

package/src/wire/formats/anthropic.ts

@@ -244,8 +244,15 @@ export const anthropicMessagesFormat: WireFormat = {
           case 'message_start': {
             const message = frame.message;
             if (!isRecord(message)) return [];
+            // `message.model` sits right beside the `message.usage` this handler
+            // already destructures. Anthropic states it once, here, and nowhere
+            // else in the stream.
+            const out: ModelStreamChunk = {};
             const usage = usageOf(message.usage);
-            return usage ? [{ usage }] : [];
+            if (usage) out.usage = usage;
+            const model = str(message.model);
+            if (model) out.model = model;
+            return Object.keys(out).length > 0 ? [out] : [];
           }
           case 'content_block_start':
             return blockStart(frame, blocks, toolIndexById);

package/src/wire/formats/openai.ts

@@ -182,6 +182,11 @@ function pushOpenAI(frame: unknown): ModelStreamChunk[] {
     }
   }
 
+  // Stated per frame and reported per frame, no dedupe: a stream that changes
+  // its mind mid-turn is a finding, and collapsing it would hide one.
+  const model = str(frame.model);
+  if (model) out.model = model;
+
   const usage = usageOf(frame.usage);
   if (usage) out.usage = usage;