@kitn.ai/ui 0.20.1 → 0.22.0

package/dist/wire/chunk.d.ts

@@ -0,0 +1,171 @@
+import { RawOrigin, ToolPart } from '../components/tool-types.js';
+import { MessagePart, MessageSource } from '../elements/chat-types.js';
+import { ReasoningOpts } from '../state/parts.js';
+/** One fragment of a tool call. */
+export interface ModelToolCallDelta {
+    /**
+     * The ONLY thing correlating fragments, and its NAMESPACE IS FORMAT-DEFINED.
+     * `openaiChatFormat` uses the position in `delta.tool_calls`;
+     * `anthropicMessagesFormat` uses the content-block index. Both are correct and
+     * both are stable within one stream, but they are not the same number, so a
+     * third-party format must pick one and stay consistent with itself.
+     */
+    index: number;
+    id?: string;
+    /** Usually whole on the first fragment; a few providers split it. */
+    name?: string;
+    /** A FRAGMENT of the JSON arguments string, not valid JSON on its own. */
+    arguments?: string;
+    /** A result the PROVIDER executed (Anthropic web_search_tool_result, an OpenAI
+     *  built-in). Completes the panel with no host work. */
+    output?: Record<string, unknown>;
+    /** A provider-executed tool that failed. */
+    outputError?: string;
+}
+/** Field names are deliberately provider-neutral. OpenAI says prompt/completion,
+ *  Anthropic says input/output; input/output is the one that reads correctly for
+ *  both. */
+export interface ModelUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /** Non-zero proves the model reasoned even when no reasoning text streamed. */
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+    costUsd?: number;
+}
+export interface ModelStreamChunk {
+    text?: string;
+    /**
+     * Reasoning delta. `''` is MEANINGFUL, not a no-op: a redacted block has no
+     * readable text but still carries a payload that must round-trip, and a format
+     * uses an empty delta to OPEN a reasoning part at the right position in the
+     * stream so block order survives into `parts`.
+     */
+    reasoning?: string;
+    /** The provider's BLOCK index. Keeps parallel reasoning blocks distinct.
+     *  Omitted means block 0, the single-block case every provider degrades to. */
+    reasoningIndex?: number;
+    /**
+     * The UNTRANSLATED provider payload for this reasoning block. Valid on a chunk
+     * with NO reasoning text at all, which is the whole point: Anthropic returns
+     * 400 if a `thinking` block is modified, reordered or RECONSTRUCTED, so an
+     * encoder has to echo the original block rather than rebuild one from `text`
+     * plus `signature`.
+     */
+    reasoningRaw?: RawOrigin;
+    /** Informational. `reasoningRaw` is the round-trip channel, not this. */
+    reasoningSignature?: string;
+    toolCalls?: ModelToolCallDelta[];
+    /** Citations the model produced. A run of consecutive `source` parts renders
+     *  as one citation row (`part="citations"`), outside the message bubble. */
+    sources?: MessageSource[];
+    /** Provider VERBATIM: 'stop' | 'tool_calls' | 'end_turn' | 'max_tokens' | ...
+     *  Normalizing in place would destroy information consumers branch on. */
+    finishReason?: string | null;
+    usage?: ModelUsage;
+    /** An in-band provider error (the HTTP response was already 200). */
+    error?: {
+        code?: string | number;
+        message: string;
+    };
+}
+/** One vocabulary across formats, for code that has to BRANCH. `finishReason`
+ *  stays beside it, verbatim, for code that has to REPORT. */
+export type StopReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
+/** Unknown reasons degrade to 'other' rather than throwing: providers add stop
+ *  reasons without warning and a new one must not take a turn down. */
+export declare function normalizeStopReason(finishReason: string | null | undefined): StopReason | undefined;
+/**
+ * The subset of the kit's `AssistantStream` the adapter drives. Declared
+ * STRUCTURALLY so the adapter has no runtime dependency on a stream
+ * implementation and can be tested against a recorder. The kit's real
+ * `AssistantStream` satisfies it as-is: same method names, same arities, and its
+ * `AssistantStream` returns are assignable to `unknown`.
+ *
+ * `addSource` is optional so a hand-rolled three-method sink still compiles.
+ */
+export interface AssistantStreamSink {
+    appendText(delta: string): unknown;
+    appendReasoning(delta: string, opts?: ReasoningOpts): unknown;
+    /** Create-or-merge. There is no separate "announce" call: handing a patch for
+     *  an unknown `toolCallId` creates the ToolPart, and every later patch merges. */
+    upsertTool(toolCallId: string, patch: Partial<ToolPart>): unknown;
+    addSource?(source: MessageSource): unknown;
+}
+/** One tool call reassembled out of the stream's fragments. */
+export interface ModelToolCall {
+    /** The delta index that correlated this call's fragments. */
+    index: number;
+    /** Provider call id (synthesised as `call_<index>` if the provider omits it). */
+    id: string;
+    name: string;
+    /** The RAW accumulated argument fragments. Echo THIS back on the next turn,
+     *  not a re-stringified parse. */
+    argumentsText: string;
+    /** Parsed arguments: present only when `argumentsText` was a valid JSON object. */
+    input?: Record<string, unknown>;
+    /** Present only for a call the PROVIDER executed. */
+    output?: Record<string, unknown>;
+    /** True when the provider ran the tool and returned its result in-stream. The
+     *  host must NOT execute these. */
+    providerExecuted?: boolean;
+    /** Why this call is unusable (malformed or truncated args, missing name). */
+    error?: string;
+}
+/** Everything one assistant turn produced. */
+export interface ModelTurn {
+    /** The turn as ORDERED MESSAGE PARTS, built with the kit's own part builders,
+     *  so it is exactly what the sink was driven with. Covers this turn only. */
+    parts: MessagePart[];
+    /** Flat concatenation of the text deltas. The provider wire format is a flat
+     *  string, so this is kept for encoders. Not the content model. */
+    text: string;
+    /** Flat concatenation of the reasoning deltas, for the same reason. */
+    reasoning: string;
+    toolCalls: ModelToolCall[];
+    sources: MessageSource[];
+    /** The provider's own word for why it stopped. Never normalized. */
+    finishReason: string | null;
+    /** The same fact in one vocabulary. Branch on this. */
+    stopReason?: StopReason;
+    error?: {
+        code?: string | number;
+        message: string;
+    };
+    usage?: ModelUsage;
+    /** How many chunks carried a NON-EMPTY reasoning delta. Zero with a non-zero
+     *  `usage.reasoningTokens` means the provider hid the thinking text. */
+    reasoningChunks: number;
+    chunks: number;
+}
+export interface ConsumeOptions {
+    /** Label for the reasoning disclosure. Defaults to 'Thinking'. */
+    reasoningLabel?: string;
+    /** Fires once per tool call the moment its arguments parse cleanly. This is
+     *  the hook a host's tool loop waits on. There is deliberately no
+     *  per-fragment callback: `ToolPart.rawInput` is written on every fragment,
+     *  so the streaming text is already on the part. */
+    onToolCallReady?: (call: ModelToolCall) => void;
+}
+/** Per-stream state for one format. */
+export interface WireFormatReader {
+    /**
+     * Map one decoded frame onto zero or more neutral chunks. Returns an ARRAY
+     * because the mapping is not one-to-one: an Anthropic `message_start` yields
+     * usage, a `content_block_start` for `tool_use` yields an id-plus-name delta,
+     * a `ping` yields nothing.
+     *
+     * MUST NOT throw on an unrecognized frame. Return `[]` instead: providers add
+     * event types without warning.
+     */
+    push(frame: unknown): ModelStreamChunk[];
+}
+/** A pluggable wire format. Values, not a flag, so a third party can add one
+ *  without a PR to this repo. */
+export interface WireFormat {
+    readonly id: string;
+    /** Called once per stream so a format can hold per-stream state. Two calls
+     *  must share NOTHING. */
+    open(): WireFormatReader;
+}

package/dist/wire/consume.d.ts

@@ -0,0 +1,26 @@
+import { AssistantStreamSink, ConsumeOptions, ModelStreamChunk, ModelToolCall, ModelToolCallDelta, ModelTurn, StopReason } from './chunk.js';
+/**
+ * Correlate tool-call fragments by `index` and drive the ToolPart lifecycle.
+ * THE HARD PART: `id`, `name` and each slice of `arguments` arrive across
+ * arbitrarily many chunks in provider-dependent order.
+ *
+ * A ToolPart is pushed (`input-streaming`) the first time a call has BOTH an id
+ * and a non-empty name: announcing earlier would create a panel whose `type` is
+ * the empty string. Everything before that is buffered and flushed at announce.
+ */
+export declare function createToolCallAccumulator(sink: AssistantStreamSink, opts?: ConsumeOptions): {
+    apply: (raw: ModelToolCallDelta) => void;
+    settle: (stopReason: StopReason | undefined, streamError?: string) => ModelToolCall[];
+};
+/**
+ * Read one turn's worth of `ModelStreamChunk`s and drive `sink` with them.
+ *
+ * The sink is expected to be the kit's `AssistantStream`, which produces a NEW
+ * message object (and a new `parts` array) on every real mutation: that is what
+ * makes `<kai-thread>` re-render. This adapter calls the sink once per delta and
+ * never batches; batching is a host concern.
+ *
+ * This is also the escape hatch for a consumer who already has neutral chunks
+ * from somewhere else and does not need a WireFormat at all.
+ */
+export declare function consumeModelStream(chunks: AsyncIterable<ModelStreamChunk>, sink: AssistantStreamSink, opts?: ConsumeOptions): Promise<ModelTurn>;

package/dist/wire/encode.d.ts

@@ -0,0 +1,221 @@
+import { ChatMessage } from '../elements/chat-types.js';
+import { MediaTypeFilter } from './media-types.js';
+export interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** One `reasoning_details` entry. Provider-owned open shape, kept as a record
+ *  for the same reason `AnthropicContentBlock` is: an opaque entry has to pass
+ *  through UNTOUCHED, and a closed type would be a list of the fields we happen
+ *  to have seen. */
+export type OpenAIReasoningDetail = Record<string, unknown>;
+/** A multimodal user message's content entries. `image_url` takes an https URL
+ *  or a `data:` URI in the same field; `file` takes `file_data`, which is a DATA
+ *  URI on this wire (`data:application/pdf;base64,...`) and not bare base64. */
+export type OpenAIContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+} | {
+    type: 'file';
+    file: {
+        filename?: string;
+        file_data: string;
+    };
+};
+export interface OpenAIWireMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** An ARRAY only when the turn carries an encodable `file` part. A text-only
+     *  turn stays a plain string, so adding attachment support changed nothing
+     *  about what an existing thread puts on the wire. */
+    content: string | OpenAIContentPart[] | null;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+    name?: string;
+    /** Only ever present when `toOpenAIMessages` was asked for it. See
+     *  `OpenAIEncodeOptions.reasoning`. */
+    reasoning_details?: OpenAIReasoningDetail[];
+}
+/** EXTENDS rather than restates the file options: `onUnencodableFile` and
+ *  `accept` mean the same thing on both wires, and a second declaration of them
+ *  here is a second place to forget to update. */
+export interface OpenAIEncodeOptions extends FileEncodeOptions {
+    /**
+     * Whether to send the assistant's own reasoning back with the thread.
+     *
+     * DEFAULT `'omit'`, and that default is a measurement, not caution. Omitting
+     * reasoning is accepted by every configuration tested -- five live omission
+     * trials plus 28 recorded live requests per configuration across the spike's
+     * conformance sweep, zero 400s -- so the path that ships today demonstrably
+     * works, while including reasoning cost about 25% more prompt tokens per round
+     * when measured (665 -> 834 on a two-round loop). A library does not get to
+     * raise every consumer's bill and add a new provider-validation surface as a
+     * side effect of a bug fix.
+     *
+     * `'include'` is for a multi-round TOOL loop, which is where OpenRouter says it
+     * pays: "when you post tool results, including the original reasoning ensures
+     * the model can continue its reasoning from where it left off". Measured
+     * accepted (HTTP 200) for a signed Anthropic block and for an OpenAI encrypted
+     * block, over the OpenAI-compatible wire.
+     *
+     * The Anthropic wire has no such knob because it has no such choice: a filtered
+     * or rebuilt thinking block there is a hard 400.
+     */
+    reasoning?: 'omit' | 'include';
+}
+/**
+ * What to do with a `file` part this wire cannot carry.
+ *
+ * DEFAULT `'throw'`, and the default is the whole point. Skipping is how
+ * attachments came to render perfectly in the thread and reach the model as
+ * nothing: the developer wires up upload, watches it work, and ships a model
+ * that cannot see the file. A throw here names the message, the part and the
+ * reason, which is strictly more than a 400 at request time would tell you.
+ *
+ * `'skip'` restores the lenient behaviour for a host that would rather send a
+ * degraded turn than fail one. It is silent, but it is silence the developer
+ * asked for by name, which is the difference that matters.
+ */
+export type UnencodableFilePolicy = 'throw' | 'skip';
+export interface FileEncodeOptions {
+    onUnencodableFile?: UnencodableFilePolicy;
+    /**
+     * Narrow which attachment media types reach the wire, as HTML `accept` syntax
+     * (`'image/*,application/pdf'`) or an array of the same.
+     *
+     * THE SAME STRING the composer takes as `<kai-chat accept="...">`, resolved by
+     * the same function against the same declaration -- so a developer writes the
+     * set once as a constant and hands it to both ends. Omitted means the kit's
+     * full capability set, which is `encodableMediaTypes()`.
+     *
+     * It can only NARROW. Naming a type the encoders cannot represent does not
+     * enable it; that would just move the failure to a provider 400.
+     */
+    accept?: MediaTypeFilter;
+}
+export type AnthropicEncodeOptions = FileEncodeOptions;
+/** Anthropic content blocks are an open, provider-owned union. Keeping them as
+ *  records is what lets a verbatim `thinking` payload pass through UNTOUCHED,
+ *  which is the entire point of this encoder. */
+export type AnthropicContentBlock = Record<string, unknown>;
+export interface AnthropicWireMessage {
+    role: 'user' | 'assistant';
+    content: AnthropicContentBlock[];
+}
+/** A message cannot be encoded without losing something the provider will reject.
+ *  Thrown at encode time, on purpose: a throw here beats a 400 at request time,
+ *  because here you still know which message and which part caused it. */
+export declare class WireEncodeError extends Error {
+    readonly messageId: string;
+    readonly partIndex: number;
+    constructor(message: string, messageId: string, partIndex: number);
+}
+/**
+ * ChatMessage[] to an OpenAI chat-completions `messages` array.
+ *
+ * ONE ChatMessage CAN BECOME SEVERAL WIRE MESSAGES. The kit streams a whole
+ * assistant turn into a single message, so text, a tool call and the model's
+ * answer to that call all live in one `parts` array. The OpenAI wire has no such
+ * shape: a `role:'tool'` result must sit between the assistant message that
+ * announced the call and whatever the model said afterwards. So the turn is
+ * SPLIT at each tool boundary, into
+ *
+ *   assistant(pre-tool text + tool_calls) -> tool(result)... -> assistant(answer)
+ *
+ * Flattening instead would put the model's answer BEFORE the result it was based
+ * on. No endpoint rejects that, which is exactly why it is worth spelling out:
+ * it quietly degrades every later round of a tool loop.
+ *
+ * Consecutive tool parts stay in ONE assistant message, because parallel calls
+ * are announced together and their results follow together.
+ *
+ * A turn that encodes to nothing is SKIPPED, never sent as `{ content: null }`
+ * with no `tool_calls`: OpenAI treats `content` as required unless `tool_calls`
+ * is present, and strict-compatible endpoints reject it.
+ *
+ * REASONING IS OPT-IN, and off by default. OpenRouter's OpenAI-compatible
+ * endpoint does have a channel on the way back in -- `reasoning_details` on the
+ * assistant message -- and `{ reasoning: 'include' }` uses it, one entry per
+ * reasoning part, in part order, reassembled by `reasoningDetailOf` rather than
+ * echoed out of `part.raw`. Read that function for which blocks make it and why.
+ * The default omits, because omitting is measured-accepted everywhere and costs
+ * about 25% fewer prompt tokens per round; see `OpenAIEncodeOptions.reasoning`.
+ *
+ * Reasoning alone still encodes to NOTHING. A block is content the model already
+ * produced, not a reason to send a turn, so a message carrying reasoning and no
+ * text and no settled tool is skipped exactly as before, rather than becoming
+ * `{ content: null }` with no `tool_calls`.
+ *
+ * `card` and `source` parts are never encoded; they are kit-side.
+ *
+ * `file` parts ARE encoded, on a USER turn, and a turn carrying nothing but an
+ * attachment is now a real message rather than nothing. Images become
+ * `image_url` (https URL or `data:` URI alike); a base64 PDF becomes a `file`
+ * part whose `file_data` is the data URI. Two cases have no form here and THROW
+ * by default: a remote PDF, because this wire's `file` part has no URL variant,
+ * and anything that is neither -- see `UnencodableFilePolicy` for why the
+ * default is a throw and not a skip.
+ *
+ * A `file` part on an ASSISTANT turn is still dropped. Neither API accepts image
+ * or document content in an assistant message, so there is nothing to encode it
+ * to; attachments belong to the user turn that sent them.
+ */
+export declare function toOpenAIMessages(messages: ChatMessage[], options?: OpenAIEncodeOptions): OpenAIWireMessage[];
+/**
+ * ChatMessage[] to an Anthropic Messages `messages` array. THE ROUND-TRIP
+ * ENCODER.
+ *
+ * A reasoning block is emitted as `part.raw.payload` verbatim and is NEVER
+ * rebuilt from `text` plus `signature`: Anthropic returns 400 if a thinking
+ * block in the most recent assistant message is modified, reordered, filtered or
+ * reconstructed. A reasoning part with no `raw`, or with a `raw` captured from
+ * some other format, therefore THROWS rather than silently producing a request
+ * that will fail.
+ *
+ * Block order follows part order, which follows stream order, with no filtering,
+ * because the API validates order too. An empty-text reasoning part (an omitted
+ * or redacted block) is still emitted: the docs require sending back every block
+ * "including any blocks with empty thinking fields".
+ *
+ * ONE ChatMessage CAN BECOME SEVERAL WIRE MESSAGES, for the same reason as
+ * `toOpenAIMessages`: the kit streams a whole assistant turn into one message, so
+ * the tool call and the model's answer to it share a `parts` array, but Anthropic
+ * carries the result in a SEPARATE user message that has to sit between them. So
+ * the turn is SPLIT at each tool boundary, into
+ *
+ *   assistant(pre-tool blocks + tool_use) -> user(tool_result)... -> assistant(answer)
+ *
+ * Flattening instead puts the model's answer BEFORE the result it was based on,
+ * and strands every later round's thinking block in the first assistant message.
+ * Consecutive tool parts stay in ONE assistant message, because parallel calls are
+ * announced together and their results come back together.
+ *
+ * Adjacent user messages are MERGED. The API combines consecutive same-role turns
+ * itself rather than rejecting them, so this is not what stands between you and a
+ * 400; it is emitted anyway because the tool-result turn and a following user turn
+ * are one turn, several OpenAI-compatible Anthropic proxies do enforce strict
+ * alternation, and the merged form is what the models are trained on. Ordering is
+ * safe by construction: `results` is only non-empty when `blocks` is, so a
+ * tool_result message always follows its assistant message and can never be
+ * appended after a plain user turn.
+ *
+ * `file` parts on a USER turn become `image` and `document` blocks, in part
+ * order. Both take `source: {type:'base64'}` and `source: {type:'url'}`, so this
+ * wire can carry a remote PDF that `toOpenAIMessages` has to refuse. Anything
+ * neither API accepts as message content THROWS by default; see
+ * `UnencodableFilePolicy`. A `file` part on an ASSISTANT turn is dropped, because
+ * an assistant message here carries only text, thinking and tool_use.
+ *
+ * Asymmetry worth knowing: `tool_use.input` is a parsed OBJECT on this wire, not
+ * a string, so it uses `input` and not `rawInput`. Only thinking blocks carry a
+ * verbatim requirement.
+ */
+export declare function toAnthropicMessages(messages: ChatMessage[], options?: AnthropicEncodeOptions): AnthropicWireMessage[];

package/dist/wire/files.d.ts

@@ -0,0 +1,116 @@
+import { AttachmentData } from '../components/attachment-types.js';
+import { MediaPolicy } from './media-types.js';
+/** Where the bytes live. `base64` carries them inline; `remote` is an address
+ *  the PROVIDER dereferences, never us. */
+export type FileSource = {
+    type: 'base64';
+    mediaType: string;
+    data: string;
+    dataUri: string;
+} | {
+    type: 'remote';
+    url: string;
+};
+/** Bytes already in hand, shaped for the provider. A union rather than an
+ *  optional `text` field so neither encoder can reach for text that is not
+ *  there, and so adding a kind is a compile error at both wires rather than a
+ *  silently unhandled branch. */
+export type ClassifiedFile = 
+/** Named for the Anthropic blocks they become. `document` is PDF-only. */
+{
+    kind: 'image';
+    mediaType: string;
+    source: FileSource;
+    filename?: string;
+} | {
+    kind: 'document';
+    mediaType: string;
+    source: FileSource;
+    filename?: string;
+}
+/** The bytes, decoded. A text file rides as TEXT CONTENT on both wires --
+ *  neither API has an arbitrary-file block, so this is the only representation
+ *  the wire can express, not a preference. `source` is narrowed to `base64`
+ *  because the text has to be in hand to inline it, and fetching a remote one
+ *  would put I/O in the encoder. */
+ | {
+    kind: 'text';
+    mediaType: string;
+    source: Extract<FileSource, {
+        type: 'base64';
+    }>;
+    filename?: string;
+    text: string;
+};
+export type FileClassification = 
+/** Ready for either wire to shape. A wire may still refuse it -- see
+ *  OpenAI and remote PDFs -- but the attachment itself is sound. */
+{
+    status: 'encodable';
+    file: ClassifiedFile;
+}
+/** Not an upload at all. A `source-document` is the citation chip an app
+ *  renders next to a RAG answer, not something the user staged to send, and
+ *  its content is already in the prompt that produced the answer. Encoding it
+ *  would send the same text twice. */
+ | {
+    status: 'kit-side';
+}
+/** Cannot reach a model. `reason` completes the sentence "Cannot encode file
+ *  part N of message X: ...", so it explains AND says what to do. */
+ | {
+    status: 'unencodable';
+    reason: string;
+};
+/**
+ * The text content a text attachment contributes to the prompt.
+ *
+ * ★ THE SWAP POINT for how a text file appears in a message, and the shape is
+ * SETTLED: `<file name="..." type="...">…</file>`. Two alternatives were weighed
+ * and rejected. A bare `filename:\n` prefix marks where the file BEGINS and not
+ * where it ends, so the next part of the turn reads as more file. An Anthropic
+ * `document` block would buy citations, but it is Anthropic-specific -- the
+ * OpenAI wire has no equivalent, so the two wires would disagree about one
+ * attachment -- and it needs a Files API upload round trip, which is I/O, in a
+ * layer that by design has none. Changing the envelope is still a change to this
+ * function and nothing else; it just is not an open question.
+ *
+ * ★ WHY THE BODY IS BARELY TOUCHED. Both attributes are escaped in full, as
+ * attributes always are. The body is not, and that is deliberate: these are
+ * source files, a reader will diff what they attached against what arrived, and
+ * XML-escaping every `<` in a TSX file would mangle the exact thing this feature
+ * exists to send and pay tokens to do it. So the body transform is the smallest
+ * one that makes the delimiter unforgeable -- the end tag, and nothing else.
+ *
+ * Left alone, that end tag is a way out of the block. A file containing `</file>`
+ * closes it early, and everything after that point reads to the model as the turn
+ * AROUND the file rather than as file content: user-supplied bytes in instruction
+ * position, reachable by anyone who can get a file in front of the composer.
+ * Escaped, it stays where it belongs. `&lt;/file&gt;` ends nothing, and it is
+ * visible in the output and reversible by eye, which a deletion or a silent
+ * substitution would not be -- a reader who spots it can say exactly what the
+ * original byte was. The OPENING tag is left untouched on purpose: it cannot end
+ * the block, and escaping it would corrupt every HTML file anyone ever attaches.
+ */
+export declare function textFileContent(file: Extract<ClassifiedFile, {
+    kind: 'text';
+}>): string;
+/**
+ * One attachment to the provider-neutral facts both encoders need.
+ *
+ * A `data:` URI's OWN media type wins over `attachment.mediaType` when they
+ * disagree: the URI describes the bytes actually present, while the field is a
+ * label the host set, and it is the bytes the provider will decode. The one
+ * exception is a URI whose media type names nothing, where there is no answer to
+ * prefer -- see below.
+ *
+ * When NOTHING names the file, it is settled by DECODING it rather than by
+ * reading its filename. That path can only ever produce text, and only when the
+ * policy still allows text, so it cannot be used to get around `accept`.
+ *
+ * `policy` narrows what counts as encodable. It defaults to the kit's full
+ * capability set, so an omitted policy behaves exactly as before for images and
+ * PDFs. It is the SAME object the composer resolves for its picker -- see
+ * `media-types.ts` for why that sharing is the point rather than a convenience.
+ */
+export declare function classifyAttachment(attachment: AttachmentData, policy?: MediaPolicy): FileClassification;

package/dist/wire/formats/anthropic.d.ts

@@ -0,0 +1,2 @@
+import { WireFormat } from '../chunk.js';
+export declare const anthropicMessagesFormat: WireFormat;

package/dist/wire/formats/openai.d.ts

@@ -0,0 +1,5 @@
+import { WireFormat } from '../chunk.js';
+/** Stateless: every frame is self-describing, so `open()` returns a reader with
+ *  no closure state. The interface still calls it per stream, which is what lets
+ *  the stateful Anthropic format use the same seam. */
+export declare const openaiChatFormat: WireFormat;

package/dist/wire/index.d.ts

@@ -0,0 +1,16 @@
+export { readModelStream, readOpenAIStream, readAnthropicStream, WireError } from './read.js';
+export type { StreamSource, ReadOptions } from './read.js';
+export { consumeModelStream, createToolCallAccumulator } from './consume.js';
+export { applyToolOutput, applyToolFailure, bufferText } from './sink-helpers.js';
+export { toOpenAIMessages, toAnthropicMessages, WireEncodeError } from './encode.js';
+export type { AnthropicContentBlock, AnthropicEncodeOptions, AnthropicWireMessage, FileEncodeOptions, OpenAIContentPart, OpenAIEncodeOptions, OpenAIReasoningDetail, OpenAIToolCall, OpenAIWireMessage, UnencodableFilePolicy, } from './encode.js';
+export { encodableMediaTypes, resolveMediaPolicy } from './media-types.js';
+export type { EncodableKind, MediaDecision, MediaPolicy, MediaPolicyOptions, MediaTypeFilter, } from './media-types.js';
+export { openaiChatFormat } from './formats/openai.js';
+export { anthropicMessagesFormat } from './formats/anthropic.js';
+export { sseDataFrames, sseJson, readableToAsyncIterable } from './sse.js';
+export type { ByteSource } from './sse.js';
+export { normalizeStopReason } from './chunk.js';
+export type { AssistantStreamSink, ConsumeOptions, ModelStreamChunk, ModelToolCall, ModelToolCallDelta, ModelTurn, ModelUsage, StopReason, WireFormat, WireFormatReader, } from './chunk.js';
+export type { ChatMessage, MessagePart, MessageSource, RawOrigin } from '../elements/chat-types.js';
+export type { ToolPart } from '../components/tool-types.js';

package/dist/wire/media-types.d.ts

@@ -0,0 +1,106 @@
+/** What a media type BECOMES on the wire. Named for the Anthropic block set,
+ *  which is the narrower of the two: `text` / `image` / `document` and nothing
+ *  else. There is no arbitrary-file block on either API, which is why a text
+ *  file has to ride as text content and a `.zip` has no representation at all. */
+export type EncodableKind = 'image' | 'document' | 'text';
+/**
+ * The media type an unnamed file gets once its BYTES have proven to be UTF-8
+ * text, and the type whose presence in the effective policy is what permits that
+ * proof to be attempted at all.
+ *
+ * `text/plain` is not a guess dressed up as a fact. It is the media type for
+ * "text, no further structure claimed", which is exactly what a successful
+ * decode establishes and the most any decode could ever establish. A `.rs` file
+ * arriving as `text/plain` is true; arriving as `text/x-rust` would be the
+ * filename talking.
+ */
+export declare const UNNAMED_TEXT_MEDIA_TYPE = "text/plain";
+/** A developer's narrowing filter. A comma-separated string (so it works as an
+ *  HTML attribute under the `kai-` contract) or an array (so it composes in JS).
+ *  Both spell the same thing; the string form is what `<kai-chat accept="...">`
+ *  takes and what the `kai` MCP scaffolder can emit as data. */
+export type MediaTypeFilter = string | readonly string[];
+/** One media type, decided against the effective set.
+ *
+ *  `unsupported` and `filtered` are split because the developer needs different
+ *  things from them: `unsupported` means fix your expectations (no API takes
+ *  this), `filtered` means fix your `accept` (the kit could have sent it). */
+export type MediaDecision = {
+    status: 'allowed';
+    kind: EncodableKind;
+} | {
+    status: 'unsupported';
+} | {
+    status: 'filtered';
+}
+/**
+ * Nobody named this file, so its media type cannot decide it. LOOK AT THE
+ * BYTES: decode them as UTF-8 (`classifyAttachment` does), and it is `text`
+ * if they decode and unencodable if they do not. Do not look at the filename.
+ *
+ * ★ THIS VARIANT IS WHERE THE DEVELOPER'S FILTER IS ENFORCED, so the caller
+ * cannot get it wrong by forgetting to check. It is returned ONLY when the
+ * effective policy still admits `text/plain` -- the one thing a decode can
+ * establish. Narrow `accept` to `image/png` and an unnamed file comes back
+ * `unsupported` instead, so the decode path is unreachable and a typeless
+ * `.rs` cannot slip past an images-only filter. That is the whole reason the
+ * check lives here rather than at each call site: there is one place to get
+ * right, and the callers physically cannot reach the bytes without being told
+ * to.
+ */
+ | {
+    status: 'undetermined';
+};
+export interface MediaPolicy {
+    /** The effective patterns: the kit's capability set narrowed by the
+     *  developer's filter. Never wider than `encodableMediaTypes()`. */
+    readonly types: readonly string[];
+    /** The same set as an HTML `accept` attribute value, ready to put on an
+     *  `<input type="file">`. This is what makes the picker and the encoder
+     *  provably one thing rather than two lists that agree today. */
+    readonly accept: string;
+    /**
+     * What this policy makes of one media type, including "I cannot tell from
+     * this, go and read the bytes" -- see `undetermined`.
+     *
+     * The primitive behind "expose information, do not make decisions": it answers
+     * a question and returns a fact, so a consumer can build their own picker,
+     * their own validation and their own error copy on top of it without the kit
+     * deciding anything on their behalf.
+     */
+    decide(mediaType: string | undefined): MediaDecision;
+}
+export interface MediaPolicyOptions {
+    /** Narrow the kit's capability set. Omitted means the full set. Anything here
+     *  that the kit cannot encode is dropped rather than honoured, because
+     *  allowing it would only relocate the failure to the provider. */
+    accept?: MediaTypeFilter;
+}
+/** Does this media type say anything at all about the bytes it labels? Exported
+ *  so `files.ts` decides "nameless" by the same rule `decide()` does, rather
+ *  than growing a second opinion about which spellings mean "I don't know". */
+export declare const namesNothing: (mediaType: string | undefined) => boolean;
+/**
+ * Every media type this kit's encoders can represent, as HTML `accept` patterns.
+ *
+ * PUBLIC ON PURPOSE, and not merely for introspection: a consumer who wants
+ * their own picker, their own validation and their own error copy can build all
+ * three against this without touching `<kai-chat>` at all. That demotes the
+ * `accept` prop from "the only door" to a convenience over a published fact,
+ * which is the composition-first shape this project already committed to.
+ */
+export declare function encodableMediaTypes(): readonly string[];
+/**
+ * The effective policy: the kit's capability set narrowed by the developer's
+ * filter, plus the text ceiling.
+ *
+ * BOTH LAYERS CALL THIS. The composer calls it to build its picker `accept`
+ * attribute and to filter what actually gets staged; the encoders call it to
+ * decide what reaches the wire. That shared call is the whole design -- it is
+ * why changing `ENCODABLE` above moves the picker and the encoder together
+ * rather than moving one and leaving the other to be noticed in production.
+ */
+export declare function resolveMediaPolicy(options?: MediaPolicyOptions): MediaPolicy;
+/** The policy every caller gets when nobody narrowed anything: the kit's full
+ *  capability set. Built once -- it has no inputs. */
+export declare const DEFAULT_MEDIA_POLICY: MediaPolicy;