@kitn.ai/ui 0.25.2 → 0.27.0

package/dist/wire/diagnostics.d.ts

@@ -0,0 +1,575 @@
+import { ModelUsage } from './chunk.js';
+import { ElementDiagnosticEvent } from '../elements/diagnostic-events.js';
+/** The envelope every diagnostic event shares. `t` is `Date.now()` at emission. */
+export interface WireDiagnosticBase {
+    type: string;
+    t: number;
+    /** Correlates every event from one provider response stream. */
+    streamId?: string;
+    /**
+     * The APP'S grouping of several reads into one logical turn. Present only
+     * when the app declared it (`ConsumeOptions.traceId`), absent otherwise.
+     *
+     * THE KIT GROUPS NOTHING ON ITS OWN. A tool loop or a set of sub-agents makes
+     * several model calls that belong together, and the kit sees one Response at
+     * a time with no way to know which ones those are. Inferring it -- by
+     * timing, by sink identity, by anything -- would produce a grouping that is
+     * right often enough to be trusted and wrong exactly when a session is
+     * confusing enough to need a panel.
+     */
+    traceId?: string;
+    /** The app's name for THIS read within the trace (`'planner'`,
+     *  `'executor'`). Present only when declared; never derived from the format,
+     *  the model or the URL. */
+    label?: string;
+}
+/** The stream opened: the source resolved and the format is about to be opened.
+ *
+ *  CONNECTION IDENTITY (`url`, `hasQuery`, `status`, `contentType`) is reported
+ *  only when the source was a `Response`, and each field is ABSENT rather than
+ *  empty when the response did not state it. A `Response` built in a test or by
+ *  a service worker has `url: ''`, and an empty string there would read as "it
+ *  was served from the origin root", which is a confident wrong answer. */
+export interface WireOpenEvent extends WireDiagnosticBase {
+    type: 'wire.open';
+    /** `opts.format.id`, e.g. `openai.chat-completions`. */
+    format: string;
+    source: 'response' | 'stream' | 'iterable';
+    /**
+     * ORIGIN AND PATHNAME ONLY. The query string is never reported, on any
+     * switch, and it is not payload either: `?api_key=sk-...` is a CREDENTIAL, a
+     * different class from the conversation content the payload key exists for,
+     * and a credential does not get a switch that turns it on. `hasQuery` carries
+     * the one bit a reader needs from it.
+     *
+     * Absent when the response did not state a URL, or stated one that does not
+     * parse.
+     */
+    url?: string;
+    /** Whether the response URL carried a query string at all. Absent exactly
+     *  when `url` is. */
+    hasQuery?: boolean;
+    /** The HTTP status. Always 2xx here -- a non-ok response throws and reports
+     *  `wire.failed` instead -- but reported verbatim rather than assumed. */
+    status?: number;
+    /**
+     * The response's `content-type` header, VERBATIM.
+     *
+     * THE FIELD THAT PAYS FOR THIS EVENT. `text/html` or `application/json` where
+     * `text/event-stream` was expected is the classic proxy or misconfiguration
+     * tell, and from inside the parse it is invisible: the frames simply never
+     * arrive and the turn resolves empty. The response knew all along.
+     */
+    contentType?: string;
+}
+/** One decoded SSE frame, and what the format made of it. */
+export interface WireFrameEvent extends WireDiagnosticBase {
+    type: 'wire.frame';
+    /** 1-based. The final `seq` equals `wire.close`'s `frames`. */
+    seq: number;
+    /** UTF-8 byte length of the raw `data:` payload. */
+    bytes: number;
+    /** Neutral chunks this frame yielded. */
+    chunks: number;
+    /**
+     * The union of `Object.keys` over this frame's chunks. THE field that earns
+     * this design: frames arriving whose chunks never once carry a content key
+     * (`text`, `reasoning`, `toolCalls`, `sources`) is the failure a chunk count
+     * alone cannot separate from a healthy stream.
+     */
+    fields: string[];
+    /** Present when this frame stated a model id. */
+    model?: string;
+    /** Content-bearing, so opt-in: the raw `data:` payload, verbatim. */
+    payload?: {
+        raw: string;
+    };
+}
+/** A message part the recorder actually produced. */
+export interface WirePartEvent extends WireDiagnosticBase {
+    type: 'wire.part';
+    /** The `MessagePart` type: 'text' | 'reasoning' | 'tool' | 'source'. */
+    variant: string;
+    index: number;
+    /** Delta LENGTH, never the delta. Present for text and reasoning only. */
+    chars?: number;
+    /** Content-bearing, so opt-in. One key per variant this write can carry:
+     *  `delta` for text and reasoning, `patch` for a tool write (which holds the
+     *  arguments and the output), `source` for a citation. */
+    payload?: {
+        delta?: string;
+        patch?: unknown;
+        source?: unknown;
+    };
+}
+/** The turn finished. Everything the widened empty-turn guard judges on. */
+export interface WireCloseEvent extends WireDiagnosticBase {
+    type: 'wire.close';
+    /** Absent when `consumeModelStream` was called directly: there were no frames. */
+    frames?: number;
+    chunks: number;
+    /** Count per variant actually produced. Empty beside a non-zero `frames` is
+     *  the wrong-dialect signature. */
+    parts: Record<string, number>;
+    finishReason: string | null;
+    stopReason?: string;
+    /** The kit's own closed vocabulary, so a panel keys its explanation off the
+     *  code and never needs the message. */
+    errorCode?: string | number;
+    usage?: ModelUsage;
+    ms: number;
+    /** Content-bearing, so opt-in: the assembled turn, plus the in-band error's
+     *  own message.
+     *
+     *  ALL THREE TERMINAL EVENTS TREAT PROVIDER MESSAGE TEXT IDENTICALLY --
+     *  `wire.close`, `wire.failed` and `wire.interrupted`. Each faces the same
+     *  hazard, that a provider's message can echo request content back, and
+     *  payload is precisely the switch that accepts it. Disagreeing here would
+     *  read as an oversight and be "fixed" later by someone with less context. */
+    payload?: {
+        text: string;
+        reasoning: string;
+        toolCalls: unknown[];
+        sources: unknown[];
+        /** The in-band error's message. Absent when the turn carried no error. */
+        message?: string;
+    };
+}
+/**
+ * The read DIED. A terminal event for a stream that never reached `wire.close`.
+ *
+ * WHY IT EXISTS: without it, a stream that errored mid-read emitted `wire.open`
+ * and then nothing at all -- no close, no failed -- and a panel showed that
+ * stream open forever. In an observability tool that is a request which
+ * silently vanished, and "the one that never finished" is precisely the request
+ * someone opens the panel to find.
+ *
+ * MUTUALLY EXCLUSIVE with `wire.close`: exactly one of the two ends a read that
+ * got as far as `wire.open`. It is emitted from `readModelStream` only, so a
+ * direct `consumeModelStream` caller (which never emitted `wire.open` either)
+ * does not get one.
+ *
+ * The error itself is UNCHANGED and still thrown: this observes and rethrows.
+ */
+export interface WireInterruptedEvent extends WireDiagnosticBase {
+    type: 'wire.interrupted';
+    /** Frames decoded before it died. */
+    frames: number;
+    /** Neutral chunks yielded before it died. */
+    chunks: number;
+    /**
+     * `'abort'` only when the error IDENTIFIES ITSELF as one (`name` of
+     * `AbortError`), which is what a fetch abort produces. Anything else is
+     * `'error'` -- a guess here would turn "the provider dropped the connection"
+     * into "your user navigated away", and those have opposite fixes.
+     */
+    reason: 'error' | 'abort';
+    /** The caught error's `name` (`'AbortError'`, `'TypeError'`). Metadata: a
+     *  closed-ish vocabulary a panel keys an explanation off. The MESSAGE is
+     *  payload. Absent when the thrown value carries no readable name. */
+    errorName?: string;
+    /** Content-bearing, so opt-in. The error's own message, which can echo
+     *  request content back the way a provider's error text does. */
+    payload?: {
+        message?: string;
+    };
+}
+/** A non-ok HTTP response: the `WireError` path, before a chunk was read. */
+export interface WireFailedEvent extends WireDiagnosticBase {
+    type: 'wire.failed';
+    status: number;
+    statusText: string;
+    bodyBytes: number;
+    bodyIsJson: boolean;
+    /** The parsed body's error CODE. Never the message: a provider's error text
+     *  can echo request content back. */
+    providerCode?: string | number;
+    /** Content-bearing, so opt-in: the raw body and the provider's own error
+     *  message, which is exactly the field that echoes request content back and
+     *  is why the code is the half that travels by default. */
+    payload?: {
+        bodyText: string;
+        message?: string;
+    };
+}
+/** One attachment the encoder handled, and what became of it.
+ *
+ *  MEDIA TYPE AND SIZE, never the name and never the bytes. A filename is
+ *  something the user typed and is payload; the media type and the size are
+ *  facts about the shape of what went on the wire. */
+export interface EncodeAttachmentReport {
+    /** As the encoder settled it, which is not always what the host declared: a
+     *  `data:` URI's own media type wins over the field beside it. Absent when
+     *  nothing named the file and classification failed before settling one. */
+    mediaType?: string;
+    /**
+     * Byte length of the bytes that went on the wire.
+     *
+     * PRESENT ONLY WHEN PAYLOAD CAPTURE IS ON. Counting it exactly is an O(n)
+     * scan of the payload, and the whole thread is re-encoded every turn, so it
+     * is a recurring per-turn cost rather than a one-off -- the same rule
+     * `EncodeRequestEvent.bytes` follows, for the same reason. The fields around
+     * it cost nothing and are always present, so the diagnosis ("this attachment
+     * was skipped") survives without the refinement ("...and it was 240 kB").
+     *
+     * ABSENT for a remote attachment even then: the provider dereferences that
+     * URL itself and the bytes never enter this process, so any number would be
+     * invented -- and `0` beside a 40 MB PDF is the exact confident zero the
+     * forward-compat rule exists to prevent.
+     *
+     * Absent always means NOT REPORTED, and is never backfilled with an estimate.
+     */
+    bytes?: number;
+    /** Whether anything at all reached the wire for this attachment. */
+    encoded: boolean;
+    /**
+     * `'encoded'` -- became an image/file/document block.
+     * `'as-text'`  -- a text file, inlined as text CONTENT, because neither API
+     *                 has an arbitrary-file block. Worth distinguishing: it is
+     *                 why an attachment can be "sent" and still not be visible to
+     *                 the model as a file.
+     * `'skipped'`  -- nothing went out for it. See `reason`.
+     */
+    disposition: 'encoded' | 'skipped' | 'as-text';
+    /** Why it was skipped, in the encoder's own words -- the same sentence the
+     *  throw would have carried. Present on `'skipped'` only. */
+    reason?: string;
+}
+/**
+ * A thread was encoded for a provider. THE WRITE-PATH HEADLINE.
+ *
+ * CONTEXT INTEGRITY is the question this answers: is the context that goes to
+ * the model the context you think it is? The encoder is the one layer that sees
+ * both sides -- the `ChatMessage[]` going in and the provider messages coming
+ * out -- so it is the only place the delta between them can be stated as data
+ * instead of as folklore.
+ *
+ * Every field is metadata: counts, variant names, media types, sizes. The
+ * encoded body itself lives under `payload`.
+ */
+export interface EncodeRequestEvent extends WireDiagnosticBase {
+    type: 'encode.request';
+    format: 'openai' | 'anthropic';
+    /** `ChatMessage[]` in. */
+    threadMessages: number;
+    /** Provider messages out. NOT the same number, by design: one assistant turn
+     *  carrying a tool call splits into three wire messages, and a truncating
+     *  host shrinks it the other way. The delta is the point. */
+    wireMessages: number;
+    /**
+     * System-role messages in the ENCODED OUTPUT.
+     *
+     * ZERO IS THE COMMON ANSWER AND IT IS THE FINDING, which is why it is a
+     * stated 0 rather than an omitted key: `ChatMessage.role` has no system
+     * member at all, so the system prompt is always being added somewhere the kit
+     * cannot see -- a server route, a gateway, a middleware. A developer chasing
+     * "why is the model ignoring its instructions" needs to know the kit is not
+     * the layer holding them.
+     */
+    systemMessages: number;
+    /** Role counts over the ENCODED OUTPUT. A role with no messages is absent
+     *  rather than 0; `systemMessages` is stated separately for that reason. */
+    byRole: Record<string, number>;
+    /** Part variants present in the THREAD, by count. */
+    partsIn: Record<string, number>;
+    /** Part variants that reached the wire, by count. `partsIn` minus this is the
+     *  round-trip loss, and each loss also has its own `encode.dropped`. */
+    partsEncoded: Record<string, number>;
+    /** One entry per `file` part the encoder handled, in encounter order. */
+    attachments: EncodeAttachmentReport[];
+    /**
+     * UTF-8 byte length of the encoded body as JSON.
+     *
+     * PRESENT ONLY WHEN PAYLOAD CAPTURE IS ON, because producing it means
+     * serializing the whole body -- every inlined attachment included -- and
+     * that is a cost the metadata stream refuses to pay for one number. When the
+     * body is already being materialized for `payload`, it is free and exact.
+     * Absent also when the body could not be stringified at all (a circular
+     * `tool.output`, a BigInt). Absent means NOT REPORTED, never zero, and it is
+     * deliberately not backfilled with an estimate.
+     */
+    bytes?: number;
+    /** Content-bearing, so opt-in. `attachments` is positionally aligned with the
+     *  metadata array above. */
+    payload?: {
+        body: unknown;
+        attachments?: Array<{
+            filename?: string;
+        }>;
+    };
+}
+/**
+ * A part that was in the thread and is NOT on the wire.
+ *
+ * THE EVENT THE WHOLE WRITE PATH IS FOR. "Your attachment rendered in the
+ * thread and was never sent to the model" was a sentence nobody could get out
+ * of the kit, and every one of these drops is deliberate, documented, and was
+ * invisible.
+ *
+ * It reports; it never decides. Nothing about what the encoders drop changed in
+ * order to add it.
+ */
+export interface EncodeDroppedEvent extends WireDiagnosticBase {
+    type: 'encode.dropped';
+    /** The `MessagePart` type, taken from the part itself at the site that
+     *  already discriminated it. */
+    variant: string;
+    /** Parts this event accounts for. Always 1 today -- every site reports per
+     *  part, because per-part is what carries the indices -- and the field exists
+     *  so a site that ever aggregates can say N without a new event type. */
+    count: number;
+    /** Position in the `ChatMessage[]` that was passed in. */
+    messageIndex?: number;
+    /** Position in that message's `parts`. */
+    partIndex?: number;
+    /** The reason documented at the drop site, in one sentence. */
+    reason: string;
+    /** Content-bearing, so opt-in: the dropped part itself, verbatim. */
+    payload?: {
+        part: unknown;
+    };
+}
+/**
+ * What the APP says it sent. Emitted only by `reportRequest`, never by the kit
+ * on its own.
+ *
+ * ★ THE ONLY EVENT THE KIT DOES NOT OBSERVE FOR ITSELF, and that is the point.
+ * In the normal shape the app's server route adds the system prompt, picks the
+ * model, and performs any RAG or guardrail injection, and NONE of it passes
+ * through the kit -- which is why `encode.request.systemMessages` is always 0.
+ * That 0 says "the system prompt is being added somewhere I cannot see"; this
+ * event is how a developer chooses to make that somewhere visible.
+ *
+ * Deliberate disclosure, so it is the app's decision and not the kit's
+ * collection. See `reportRequest` for why that distinction is load-bearing.
+ */
+export interface AppRequestEvent extends WireDiagnosticBase {
+    type: 'app.request';
+    /** Length of the body's `messages` array. Absent when there was no array to
+     *  count -- which is a different fact from a request carrying none. */
+    messages?: number;
+    /**
+     * Role counts over that array, INCLUDING `system`.
+     *
+     * This is the half the kit structurally cannot see: `ChatMessage.role` has no
+     * system member at all, so a system prompt exists only in the body the app
+     * builds. A role nobody sent is absent rather than 0.
+     *
+     * ★ THESE COUNTS NEED NOT SUM TO `messages`, and a consumer must not assume
+     * they do. An entry stating no readable role is counted in `messages` and
+     * contributes to no bucket -- a body of 5 messages where 1 states a role
+     * gives `messages: 5` with `byRole: { user: 1 }`. That is deliberate:
+     * bucketing the rest under `'unknown'` would invent a role nobody sent. A
+     * panel rendering these as a stacked bar should render the difference as
+     * unattributed rather than scaling it away.
+     */
+    byRole?: Record<string, number>;
+    /**
+     * System-role messages, stated explicitly whenever the array could be counted.
+     *
+     * ZERO IS A FINDING and must be distinguishable from "not reported": it says
+     * nothing is setting a system prompt at this layer either. Reading it off
+     * `byRole.system` could not tell those apart, which is the whole reason this
+     * field is separate -- and it lines up directly against
+     * `EncodeRequestEvent.systemMessages` for the comparison that answers "are
+     * additional prompts being added?".
+     */
+    systemMessages?: number;
+    /** Length of the body's `tools` array. A present-but-empty array reports 0,
+     *  which is a real and different state from the key being absent: it says the
+     *  app meant to send tools and sent none. Absent when there is no array. */
+    tools?: number;
+    /**
+     * The REQUESTED model, read verbatim from the body.
+     *
+     * ★ NEVER INFERRED, and absent stays absent. Paired with `WireFrameEvent`'s
+     * SERVED model this is the devtools spec's "selected Claude, served gpt-4o"
+     * finding -- two independent facts a panel COMPARES and never reconciles.
+     * Deriving either half from the other would make them agree in exactly the
+     * mismatch case the pair exists to catch.
+     */
+    model?: string;
+    /** ORIGIN AND PATHNAME ONLY, on the same terms as `WireOpenEvent.url`: a
+     *  query string can carry a credential, and a credential is not conversation
+     *  content, so it does not travel under any switch. Absent when no URL was
+     *  supplied or it did not parse. */
+    url?: string;
+    /** Whether that URL carried a query string. Absent exactly when `url` is. */
+    hasQuery?: boolean;
+    /**
+     * UTF-8 byte length of the body AS IT WILL BE SENT.
+     *
+     * PRESENT ONLY UNDER PAYLOAD CAPTURE, by the same rule
+     * `EncodeRequestEvent.bytes` follows: measuring means materializing the body,
+     * and a request is made every turn.
+     *
+     * ABSENT WHENEVER IT CANNOT BE KNOWN EXACTLY, which is a larger set than it
+     * looks. A string, a JSON-declaring body, a `Blob`/`File` and an
+     * `ArrayBuffer` or view can all be measured exactly and are. A `FormData`, a
+     * `ReadableStream`, a `URLSearchParams`, a `Map`, or a circular body cannot,
+     * and report nothing -- never the length of the `"{}"` they happen to
+     * stringify to, which is how a 40 MB upload came to report `bytes: 2`.
+     */
+    bytes?: number;
+    /**
+     * Content-bearing, so opt-in: the body itself, exactly as handed over.
+     *
+     * ★ PUBLISHED BY REFERENCE, NOT CLONED. A subscriber that mutates
+     * `payload.body` mutates the object the app is about to send. Deep-cloning
+     * every request would be expensive on exactly the large bodies worth
+     * inspecting, and would defeat the point of handing the real thing over -- so
+     * the contract is that a consumer TREATS THIS AS READ-ONLY. Clone it yourself
+     * if you intend to edit it.
+     */
+    payload?: {
+        body: unknown;
+    };
+}
+export type WireDiagnosticEvent = WireOpenEvent | WireFrameEvent | WirePartEvent | WireCloseEvent | WireFailedEvent | WireInterruptedEvent | EncodeRequestEvent | EncodeDroppedEvent | AppRequestEvent;
+/** The three correlating fields, built ONCE per read and spread onto every
+ *  event it emits. One definition so `read.ts` and `consume.ts` cannot drift
+ *  about which events carry a trace. */
+export interface WireCorrelation {
+    streamId: string;
+    traceId?: string;
+    label?: string;
+}
+/**
+ * INTERNAL. The correlation for one read.
+ *
+ * ABSENT, NOT UNDEFINED. `traceId` and `label` are omitted entirely when the app
+ * did not declare them, so a consumer's `'traceId' in event` answers "did the
+ * app group this" rather than "did the kit have an opinion". A key present with
+ * an undefined value is the kit claiming it looked, and it is not in a position
+ * to make that claim.
+ */
+export declare function wireCorrelation(streamId: string, opts: {
+    traceId?: string;
+    label?: string;
+}): WireCorrelation;
+/**
+ * EVERY diagnostic event, from every layer that emits one.
+ *
+ * There is one emitter and one stream, so there has to be one union. `wire.*`
+ * events say what the parse pipeline saw; `element.*` events say what a
+ * consumer did to a live custom element. A panel wants both and wants them in
+ * arrival order, which is precisely why they share a channel rather than
+ * getting one each.
+ *
+ * WIDENING, not repurposing: no existing field changed meaning and no existing
+ * type was renamed, so the forward-compat rule at the top of this file holds. A
+ * consumer that already switches on `type` and ignores what it does not know --
+ * which the contract requires -- is unaffected. What DOES move is the static
+ * type a `.d.ts` consumer sees on `subscribeWireDiagnostics`, `drain()` and
+ * `attach()`: it is now the wider union, so code that assigned the callback
+ * parameter straight into a `WireDiagnosticEvent` needs a narrowing check it
+ * should have had anyway.
+ */
+export type KaiDiagnosticEvent = WireDiagnosticEvent | ElementDiagnosticEvent;
+/**
+ * Narrow the shared stream to the element half — and, by negation, to the wire
+ * half, which is what most callers actually want:
+ *
+ *   if (isElementDiagnosticEvent(e)) { … } else { e.streamId … }
+ *
+ * WHY THIS DIRECTION and not an `isWireDiagnosticEvent`. The element family is
+ * CLOSED and small; the non-element side is the one that keeps growing, and it
+ * does not even share one prefix -- `wire.*`, `encode.*` and `app.*` are all in
+ * `WireDiagnosticEvent` today, with `kit.warn` queued in the inventory behind
+ * them. That is not a prediction: `encode.*` and `app.*` both arrived while this
+ * branch was open, so a positive `wire.*` allowlist written a fortnight ago
+ * would already be answering "not a wire event" for two live families. Testing
+ * the closed set and taking the complement stays correct as the open set grows.
+ *
+ * Exists because a panel, and every test in this repo that reads `streamId` or
+ * `traceId` off "every event", needs exactly this one check now that two layers
+ * share one channel. The prefix is pinned by `element-artifact-divergence.test.ts`.
+ */
+export declare function isElementDiagnosticEvent(e: KaiDiagnosticEvent): e is ElementDiagnosticEvent;
+type Subscriber = (e: KaiDiagnosticEvent) => void;
+/**
+ * Subscribe to wire diagnostics. Returns an unsubscribe function.
+ *
+ * SSR-safe: `globalThis` is available in every runtime the kit imports into, and
+ * nothing here touches `window`.
+ */
+export declare function subscribeWireDiagnostics(fn: Subscriber): () => void;
+/**
+ * INTERNAL. Every emission site gates on this BEFORE constructing an event
+ * object, which is what makes the no-subscriber path cost one symbol read and
+ * allocate nothing -- not even the shared state.
+ */
+export declare function wireDiagnosticsActive(): boolean;
+/**
+ * INTERNAL. Whether content-bearing values may ride under the `payload` key.
+ *
+ * A SEPARATE SWITCH FROM `wireDiagnosticsActive`, and the separation is the
+ * security property rather than a preference. The panel is a pasted script tag
+ * on a live site and `?kai-devtools=1` is guessable; a stranger who guesses it
+ * gets the SHAPE of a conversation and not one word of its content. Turning
+ * that into content takes a second, deliberate signal that no URL can set.
+ *
+ * Every emission site checks this INSIDE its `wireDiagnosticsActive()` branch
+ * and builds the payload object only then, so a session with a subscriber and
+ * no payload switch pays one extra boolean read per event.
+ */
+export declare function wirePayloadActive(): boolean;
+/**
+ * INTERNAL. Turn payload capture on or off.
+ *
+ * Called by the devtools hook at install, from the payload signal it read
+ * synchronously. It is not part of the public surface: a consumer who can flip
+ * this can make the kit start recording its own users' conversations, and that
+ * is a decision the app makes through the signal, deliberately, not something a
+ * dependency can reach in and do.
+ *
+ * Turning it ON allocates the shared state; turning it OFF does not, so the
+ * dormant no-signal path still allocates nothing at all.
+ */
+export declare function setWirePayloadCapture(on: boolean): void;
+/**
+ * INTERNAL. The `payload` key, or nothing.
+ *
+ * Every content-bearing value in this module goes through here, which is what
+ * makes the boundary reviewable: there is one call to grep for, one key to
+ * strip in a test, and no field-by-field audit. The builder is a THUNK so that
+ * with the switch off nothing is read, copied or stringified -- the cost of
+ * carrying an unused payload is a boolean.
+ */
+export declare function withPayload<T>(build: () => T): {
+    payload: T;
+} | Record<string, never>;
+/**
+ * INTERNAL. Deliver to every subscriber.
+ *
+ * Iterates a SNAPSHOT so a subscriber that unsubscribes (or subscribes) during
+ * delivery cannot make the loop skip its neighbour. Each call is wrapped
+ * individually: a panel that throws must not take down the stream it is
+ * watching, nor starve the other subscribers. The throw is swallowed rather
+ * than re-reported because there is nowhere to report it TO that is not itself
+ * a subscriber.
+ */
+export declare function emitWireDiagnostic(e: KaiDiagnosticEvent): void;
+/**
+ * INTERNAL. One id per provider response stream.
+ *
+ * It correlates diagnostics AND namespaces reasoning block indices. Anthropic
+ * restarts content-block indices at 0 on every message, and a tool loop reads
+ * several messages into ONE assistant turn, so without this round 2's block 0
+ * merges into round 1's part and overwrites its verbatim `raw`. See
+ * `appendReasoningPart`.
+ *
+ * A monotonic counter, not a UUID: this never leaves the process, is compared
+ * only for equality against parts built in the same process, and a counter keeps
+ * the value short and reproducible in test output.
+ *
+ * It lives HERE rather than in `consume.ts` because `readModelStream` opens the
+ * format and counts frames before `consumeModelStream` runs, and every event
+ * from one read has to carry the same id.
+ *
+ * The counter sits in the SHARED state, so two copies of this module continue
+ * one sequence instead of both restarting at `wire-1` and minting the same id
+ * for different streams. See the note on `STATE_KEY`.
+ */
+export declare function nextStreamId(): string;
+export {};

package/dist/wire/encode-probe.d.ts

@@ -0,0 +1,70 @@
+import { EncodeAttachmentReport } from './diagnostics.js';
+/**
+ * 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 declare function base64Bytes(data: string): number;
+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 declare function createEncodeProbe(opts: {
+    traceId?: string;
+    label?: string;
+}): EncodeProbe;

package/dist/wire/encode.d.ts

@@ -100,6 +100,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;
 /** Anthropic content blocks are an open, provider-owned union. Keeping them as