toolnexus 0.16.0 → 0.17.0

package/src/client.ts

@@ -6,6 +6,8 @@
 import type { Toolkit } from "./toolkit.js"
 import type { ToolResult, Request, Answer } from "./types.js"
 import { pendingOf } from "./types.js"
+import type { ContentPart, PromptInput, UnsupportedPartMode } from "./content.js"
+import { toOpenAIWire, toAnthropicWire, checkPromptParts, type WireOptions } from "./wire.js"
 import type { TranslateRequest, TranslateResult, TranslatedToolCall } from "./translate.js"
 import {
   finishReasonFor,
@@ -62,6 +64,13 @@ export interface ClientOptions {
    * today. A "retry" is always bounded by `retries`; the classifier cannot loop unbounded.
    * There is no "suspend" tier — suspension (§10) stays a user-action pause, not an error path. */
   onError?: (info: ErrorInfo) => ErrorTier
+  /** §1B. Reject a content part carrying more than this many **decoded** bytes (never the
+   * +33% base64 string). Unset ⇒ no limit, as today. */
+  maxPartBytes?: number
+  /** §8A. Overrides the provenance rule uniformly: `"error"` fails on any part the style
+   * cannot represent (attached or tool-derived), `"text"` degrades every one of them to a
+   * text placeholder. Unset ⇒ attached parts error, derived parts degrade. */
+  onUnsupportedPart?: UnsupportedPartMode
 }
 
 /** §8 Resilience. What to do with a failed LLM call. */
@@ -384,7 +393,7 @@ export class Client {
   /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
    * matches the pre-change body so a no-options call is byte-identical. */
   private openaiBody(messages: any[], tools: any[], stream: boolean): Record<string, any> {
-    const b: Record<string, any> = { model: this.opts.model, messages }
+    const b: Record<string, any> = { model: this.opts.model, messages: toOpenAIWire(messages, this.wireOpts()) }
     if (tools.length) {
       b.tools = tools
       b.tool_choice = "auto"
@@ -398,12 +407,17 @@ export class Client {
 
   /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
   private anthropicBody(system: string, messages: any[], tools: any[], stream: boolean): Record<string, any> {
-    const b: Record<string, any> = { model: this.opts.model, max_tokens: 4096, system, messages }
+    const b: Record<string, any> = { model: this.opts.model, max_tokens: 4096, system, messages: toAnthropicWire(messages, this.wireOpts()) }
     if (tools.length) b.tools = tools
     if (stream) b.stream = true
     return this.finalizeBody(b)
   }
 
+  /** The §8A/§1B shaping options every wire build shares. */
+  private wireOpts(): WireOptions {
+    return { onUnsupportedPart: this.opts.onUnsupportedPart, maxPartBytes: this.opts.maxPartBytes }
+  }
+
   /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
   metrics(): string {
     return this.registry.render()
@@ -427,7 +441,8 @@ export class Client {
     this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart, error: e instanceof Error ? e.message : String(e) })
   }
 
-  async run(prompt: string, ctx: { toolkit: Toolkit; signal?: AbortSignal; history?: any[] }): Promise<RunResult> {
+  async run(prompt: PromptInput, ctx: { toolkit: Toolkit; signal?: AbortSignal; history?: any[] }): Promise<RunResult> {
+    checkPromptParts(prompt, this.wireOpts())
     return this.opts.style === "anthropic"
       ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
       : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history)
@@ -592,7 +607,7 @@ export class Client {
    * the answer — so the next `ask` with the same `id` continues it. Without an
    * `id` it is a stateless one-shot (identical to `run`).
    */
-  async ask(prompt: string, ctx: { toolkit: Toolkit; id?: string; on_text?: (delta: string) => void; signal?: AbortSignal }): Promise<RunResult> {
+  async ask(prompt: PromptInput, ctx: { toolkit: Toolkit; id?: string; on_text?: (delta: string) => void; signal?: AbortSignal }): Promise<RunResult> {
     // Block-style streaming: run the streaming loop, forward text deltas, still return the
     // final RunResult. Memory (id load/save) is handled by stream() itself, so no duplication.
     if (ctx.on_text) {
@@ -620,7 +635,8 @@ export class Client {
    * With an `id`, it is stateful (like `ask`): the thread's transcript is loaded as history before
    * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
    */
-  async *stream(prompt: string, ctx: { toolkit: Toolkit; id?: string; signal?: AbortSignal }): AsyncGenerator<StreamEvent, void, unknown> {
+  async *stream(prompt: PromptInput, ctx: { toolkit: Toolkit; id?: string; signal?: AbortSignal }): AsyncGenerator<StreamEvent, void, unknown> {
+    checkPromptParts(prompt, this.wireOpts())
     const history = ctx.id ? (await this.store.get(ctx.id)) ?? [] : undefined
     const gen = this.opts.style === "anthropic"
       ? this.streamAnthropic(prompt, ctx.toolkit, ctx.signal, history)
@@ -730,7 +746,7 @@ export class Client {
   }
 
   // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
-  private async runOpenAI(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
+  private async runOpenAI(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const runStart = Date.now()
@@ -783,7 +799,7 @@ export class Client {
         // on resume). Mirrors the streaming path.
         for (const s of settled) {
           toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata })
-          messages.push({ role: "tool", tool_call_id: s.call.id, content: s.result.output })
+          messages.push(toolMessage(s.call.id, s.call.function.name, s.result))
           if (s.halted) return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage)
         }
       }
@@ -830,7 +846,7 @@ export class Client {
   }
 
   // ---- Anthropic-style: POST {baseUrl}/messages ----
-  private async runAnthropic(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
+  private async runAnthropic(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const base = this.opts.baseUrl.replace(/\/$/, "")
@@ -890,7 +906,7 @@ export class Client {
         let halted: Request | undefined
         for (const s of settled) {
           toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata })
-          content.push({ type: "tool_result", tool_use_id: s.use.id, content: s.result.output, is_error: s.result.isError })
+          content.push(toolResultBlock(s.use.id, s.result))
           if (s.halted) { halted = s.halted; break }
         }
         messages.push({ role: "user", content })
@@ -904,7 +920,7 @@ export class Client {
   }
 
   // ---- Streaming: OpenAI-style ----
-  private async *streamOpenAI(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
+  private async *streamOpenAI(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const runStart = Date.now()
@@ -982,13 +998,13 @@ export class Client {
             result = r.result
             if (r.halted) {
               toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-              messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
+              messages.push(toolMessage(c.id, c.name, result))
               yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
               return
             }
           }
           toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-          messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
+          messages.push(toolMessage(c.id, c.name, result))
           yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError }
         }
       }
@@ -1000,7 +1016,7 @@ export class Client {
   }
 
   // ---- Streaming: Anthropic-style ----
-  private async *streamAnthropic(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
+  private async *streamAnthropic(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const runStart = Date.now()
@@ -1073,14 +1089,14 @@ export class Client {
             result = r.result
             if (r.halted) {
               toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-              results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
+              results.push(toolResultBlock(u.id, result))
               messages.push({ role: "user", content: results })
               yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
               return
             }
           }
           toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-          results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
+          results.push(toolResultBlock(u.id, result))
           yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError }
         }
         messages.push({ role: "user", content: results })
@@ -1233,7 +1249,7 @@ export class Conversation {
   constructor(private readonly client: Client, private readonly toolkit: Toolkit, private readonly signal?: AbortSignal) {}
 
   /** Send the next user turn; prior history is retained automatically. */
-  async send(prompt: string): Promise<RunResult> {
+  async send(prompt: PromptInput): Promise<RunResult> {
     const result = await this.client.run(prompt, { toolkit: this.toolkit, signal: this.signal, history: this.messages })
     this.messages = result.messages
     return result
@@ -1279,6 +1295,27 @@ function safeJson(s: string): Record<string, unknown> {
   }
 }
 
+/**
+ * A canonical `tool` turn. With no parts this is byte-identical to the pre-0.17 message;
+ * with parts it also carries them (and the tool `name` the §8A relocation header needs) —
+ * both consumed and stripped by the wire build, so neither reaches OpenAI.
+ */
+function toolMessage(id: string | undefined, name: string, result: ToolResult): any {
+  const m: any = { role: "tool", tool_call_id: id, content: result.output }
+  if (result.parts?.length) {
+    m.name = name
+    m.parts = result.parts
+  }
+  return m
+}
+
+/** A canonical Anthropic `tool_result` block; parts ride along and are emitted natively. */
+function toolResultBlock(id: string | undefined, result: ToolResult): any {
+  const b: any = { type: "tool_result", tool_use_id: id, content: result.output, is_error: result.isError }
+  if (result.parts?.length) b.parts = result.parts
+  return b
+}
+
 function lastText(messages: any[]): string {
   for (let i = messages.length - 1; i >= 0; i--) {
     if (messages[i].role === "assistant" && typeof messages[i].content === "string") return messages[i].content

package/src/content.ts

@@ -0,0 +1,448 @@
+/**
+ * Multimodal content parts (SPEC.md §1B, §8A).
+ *
+ * One `ContentPart` union — `text | image | file | audio` — is how non-text data enters
+ * the loop (a prompt), comes back from a tool (`ToolResult.parts`), and survives MCP.
+ * A part is **bytes-or-URL, never a path**: a path does not survive a persisted and
+ * replayed transcript, nor the MCP / A2A process boundary, so the edge constructors
+ * (`attach`, `text`) normalise a path / native bytes / a `data:` URL at construction.
+ *
+ * Emission lives here too, not in `adapters.ts` (which is tool-*schema* only): each
+ * `(style, part.type)` pair has either a defined block shape or an explicit refusal, and
+ * the encoded block is checked against a **positive allowlist** before it can reach the
+ * wire — because an unknown block type upstream returns HTTP 200 with the content
+ * silently discarded, which is the exact bug this module exists to remove.
+ */
+import fs from "node:fs/promises"
+import path from "node:path"
+
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image"; mimeType: string; data?: string; url?: string }
+  | { type: "file"; mimeType: string; data?: string; url?: string; name?: string }
+  | { type: "audio"; mimeType: string; data?: string; url?: string }
+
+/** A prompt is a string or an ordered list of parts — ordering is semantic to a model. */
+export type PromptInput = string | ContentPart[]
+
+/** The two provider styles that have a request path (`toGemini` is declarations only). */
+export type PartStyle = "openai" | "anthropic"
+
+/** How a part got here. Drives the unsupported-part rule (§8A): the caller asked for an
+ *  attached part, so silently changing it is the betrayal; nobody asked for a part an MCP
+ *  server volunteered, so failing the run over it is a regression. */
+export type PartProvenance = "attached" | "derived"
+
+/** What to do with a part the style cannot represent; overrides provenance uniformly. */
+export type UnsupportedPartMode = "error" | "text"
+
+/** Why a part could not be constructed or sent (§1B / §8A). `code` is the machine-readable half. */
+export class ContentPartError extends Error {
+  constructor(
+    message: string,
+    readonly code: "source-conflict" | "source-missing" | "unknown-extension" | "too-large" | "unsupported",
+  ) {
+    super(message)
+    this.name = "ContentPartError"
+  }
+}
+
+/**
+ * The media extension table (§6 `read`) — fixed, shared with the edge constructors,
+ * identical in every port. No magic-byte sniffing and no platform mime database:
+ * `/etc/mime.types` varies per machine and would break cross-port parity.
+ */
+export const MEDIA_TYPES: Record<string, { mimeType: string; type: "image" | "file" | "audio" }> = {
+  png: { mimeType: "image/png", type: "image" },
+  jpg: { mimeType: "image/jpeg", type: "image" },
+  jpeg: { mimeType: "image/jpeg", type: "image" },
+  gif: { mimeType: "image/gif", type: "image" },
+  webp: { mimeType: "image/webp", type: "image" },
+  pdf: { mimeType: "application/pdf", type: "file" },
+  mp3: { mimeType: "audio/mpeg", type: "audio" },
+  wav: { mimeType: "audio/wav", type: "audio" },
+}
+
+/** Lower-cased extension without the dot, or "" when there is none. */
+export function extensionOf(p: string): string {
+  const ext = path.extname(p)
+  return ext ? ext.slice(1).toLowerCase() : ""
+}
+
+/** The table entry for a path/URL, or undefined when the extension is not media. */
+export function mediaTypeFor(p: string): { mimeType: string; type: "image" | "file" | "audio" } | undefined {
+  return MEDIA_TYPES[extensionOf(p)]
+}
+
+/** Part kind for a mime type: `image/*` ⇒ image, `audio/*` ⇒ audio, everything else ⇒ file. */
+export function partTypeForMime(mimeType: string): "image" | "file" | "audio" {
+  if (mimeType.startsWith("image/")) return "image"
+  if (mimeType.startsWith("audio/")) return "audio"
+  return "file"
+}
+
+/** Decoded byte length of standard, padded base64 — without decoding it (RFC 4648 §4:
+ *  `floor(len/4)*3 - padCount`). `<bytes>` in every rendered string is a plain integer, never
+ *  a fraction, so this floors the group count rather than assuming `len` is a multiple of 4. */
+export function base64Bytes(b64: string): number {
+  const n = b64.length
+  if (n === 0) return 0
+  let pad = 0
+  if (b64.endsWith("==")) pad = 2
+  else if (b64.endsWith("=")) pad = 1
+  return Math.floor(n / 4) * 3 - pad
+}
+
+/** Decoded byte length of a part's payload; a url-only part carries no bytes here. */
+export function partBytes(part: ContentPart): number {
+  if (part.type === "text") return Buffer.byteLength(part.text, "utf8")
+  return part.data ? base64Bytes(part.data) : 0
+}
+
+/** §1B token estimate for a part, from its decoded byte count: `max(85, floor(bytes/750))`.
+ *  Measured against real providers: image cost is not proportional to bytes, so this is an
+ *  explicit estimate, not a count — but it is normative and lives with the part logic so a
+ *  budgeting helper (e.g. `agents.estimateTokens`) cannot silently diverge from it. */
+export const PART_BYTES_PER_TOKEN = 750
+export const MIN_PART_TOKENS = 85
+export function partTokens(bytes: number): number {
+  return Math.max(MIN_PART_TOKENS, Math.floor(bytes / PART_BYTES_PER_TOKEN))
+}
+
+/**
+ * How a part appears in a log line or a §9 event: `{type, mimeType, bytes}` — never `data`.
+ * Same rule as never-log-headers: part payloads are user content.
+ */
+export function describePart(part: ContentPart): Record<string, unknown> {
+  if (part.type === "text") return { type: "text", bytes: partBytes(part) }
+  return { type: part.type, mimeType: part.mimeType, bytes: partBytes(part) }
+}
+
+/** A one-line, payload-free rendering of a part — for `output` text and placeholders. */
+export function summarizePart(part: ContentPart): string {
+  return part.type === "text" ? part.text : `${part.type} (${part.mimeType}, ${partBytes(part)} bytes)`
+}
+
+/** Validate the §1B invariant: exactly one of `data` / `url`. */
+export function validatePart(part: ContentPart, maxPartBytes?: number): ContentPart {
+  if (part.type === "text") return part
+  const hasData = part.data !== undefined && part.data !== null
+  const hasUrl = part.url !== undefined && part.url !== null
+  if (hasData && hasUrl) {
+    throw new ContentPartError(`content part "${part.type}" carries both data and url — supply exactly one`, "source-conflict")
+  }
+  if (!hasData && !hasUrl) {
+    throw new ContentPartError(`content part "${part.type}" carries neither data nor url — supply exactly one`, "source-missing")
+  }
+  if (maxPartBytes !== undefined && hasData) {
+    const bytes = base64Bytes(part.data!)
+    if (bytes > maxPartBytes) {
+      throw new ContentPartError(`content part "${part.type}" is ${bytes} decoded bytes, over the maxPartBytes limit of ${maxPartBytes}`, "too-large")
+    }
+  }
+  return part
+}
+
+/** True when a value looks like a `ContentPart` (as opposed to a provider-native block). */
+export function isContentPart(v: unknown): v is ContentPart {
+  if (!v || typeof v !== "object") return false
+  const t = (v as any).type
+  if (t === "text") return typeof (v as any).text === "string"
+  if (t === "image" || t === "file" || t === "audio") return typeof (v as any).mimeType === "string"
+  return false
+}
+
+// --------------------------------------------------------------------------- //
+// Edge constructors — a path / bytes / a data: URL never enters the part itself.
+// --------------------------------------------------------------------------- //
+
+/** A text part. */
+export function text(value: string): ContentPart {
+  return { type: "text", text: value }
+}
+
+/** Options for {@link attach}. */
+export interface AttachOptions {
+  /** Overrides the extension table; **required** for raw bytes and for an unlisted extension. */
+  mimeType?: string
+  /** Filename carried on a `file` part (OpenAI's `file.filename`). Defaults to the basename. */
+  name?: string
+  /** Reject a payload over this many **decoded** bytes (never the +33% base64 string). */
+  maxPartBytes?: number
+}
+
+/** Everything the edge constructor accepts (§1B): a path / `data:` / `https:` string, native
+ *  bytes in any of their JS spellings, or the host's own file object. Whatever comes in, only
+ *  `mimeType` + base64 `data` (or a `url`) lands in the part — accept broadly, store narrowly. */
+export type AttachSource = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob
+
+/** A `Blob`/`File` — duck-typed, so a Blob from another realm or a polyfill is accepted too. */
+function isBlobLike(v: unknown): v is Blob {
+  return !!v && typeof v === "object" && typeof (v as any).arrayBuffer === "function" && !ArrayBuffer.isView(v)
+}
+
+/** Normalise any native byte spelling to a `Uint8Array` view over the same bytes — an
+ *  `ArrayBufferView` that is not a `Uint8Array` must be re-viewed, not passed to
+ *  `Buffer.from`, which would read it as an array of numbers. */
+function toBytes(source: Uint8Array | ArrayBuffer | ArrayBufferView): Uint8Array {
+  if (source instanceof Uint8Array) return source
+  if (ArrayBuffer.isView(source)) return new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
+  return new Uint8Array(source)
+}
+
+/** The typed §1B refusal for a name/path whose extension is not in the fixed table. */
+function unknownExtension(nameOrPath: string): ContentPartError {
+  const ext = extensionOf(nameOrPath)
+  return new ContentPartError(
+    `no mime type for extension "${ext || "(none)"}" — pass an explicit mimeType (mime is never sniffed)`,
+    "unknown-extension",
+  )
+}
+
+/**
+ * The edge constructor: hand it whatever you actually have and get a path-free part.
+ *
+ * | given | becomes |
+ * |---|---|
+ * | a filesystem path | bytes read now, base64d now; mime from the fixed extension table |
+ * | native bytes (`Uint8Array`/`Buffer`/`ArrayBuffer`/any `ArrayBufferView`) | base64d now; `mimeType` required |
+ * | a `Blob` / `File` | read to bytes **now**; mime from `blob.type`, else the extension table via `File.name` |
+ * | `data:<mime>;base64,<b64>` | parsed into `{mimeType, data}` — never stored as a url |
+ * | an `http(s):` URL | kept as `url` |
+ */
+export async function attach(source: AttachSource, opts: AttachOptions = {}): Promise<ContentPart> {
+  if (typeof source === "string") {
+    if (source.startsWith("data:")) return fromDataUrl(source, opts)
+    if (/^https?:\/\//i.test(source)) return fromUrl(source, opts)
+    return fromPath(source, opts)
+  }
+  if (isBlobLike(source)) return fromBlob(source, opts)
+  if (!opts.mimeType) {
+    throw new ContentPartError("attach(bytes) requires an explicit mimeType — bytes carry no extension to read", "unknown-extension")
+  }
+  return fromBytes(toBytes(source), opts.mimeType, opts)
+}
+
+/**
+ * Build a part from a `Blob` or `File`, consuming it **eagerly** — a part holding a half-read
+ * stream would not survive the transcript boundary any better than a path does (§1B).
+ *
+ * Mime comes from `blob.type` when it is non-empty, else from the fixed extension table applied
+ * to `File.name`; an explicit `opts.mimeType` beats both. A `File`'s name is carried onto a
+ * `file` part unless `opts.name` overrides it.
+ */
+export async function fromBlob(blob: Blob, opts: AttachOptions = {}): Promise<ContentPart> {
+  const name = typeof (blob as any).name === "string" ? String((blob as any).name) : undefined
+  const mimeType = opts.mimeType || (blob.type || undefined) || (name ? mediaTypeFor(name)?.mimeType : undefined)
+  if (!mimeType) throw unknownExtension(name ?? "")
+  const bytes = new Uint8Array(await blob.arrayBuffer())
+  return finish(partTypeForMime(mimeType), mimeType, { data: Buffer.from(bytes).toString("base64") }, name ? { name, ...opts } : opts)
+}
+
+/** Build a part from in-memory bytes. `mimeType` is required — bytes carry no extension. */
+export function fromBytes(bytes: Uint8Array | ArrayBuffer | ArrayBufferView, mimeType: string, opts: AttachOptions = {}): ContentPart {
+  const data = Buffer.from(toBytes(bytes)).toString("base64")
+  return finish(partTypeForMime(mimeType), mimeType, { data }, opts)
+}
+
+/** Read a file now and base64 it now, so the part never carries the path (§1B). */
+export async function fromPath(p: string, opts: AttachOptions = {}): Promise<ContentPart> {
+  const mimeType = opts.mimeType ?? mediaTypeFor(p)?.mimeType
+  if (!mimeType) throw unknownExtension(p)
+  const bytes = await fs.readFile(p)
+  return finish(partTypeForMime(mimeType), mimeType, { data: bytes.toString("base64") }, { name: path.basename(p), ...opts })
+}
+
+/** Parse `data:<mime>;base64,<b64>` into `{mimeType, data}`, so two spellings of the same
+ *  bytes cannot diverge downstream. */
+export function fromDataUrl(url: string, opts: AttachOptions = {}): ContentPart {
+  const m = /^data:([^;,]*)(;base64)?,(.*)$/s.exec(url)
+  if (!m) throw new ContentPartError("malformed data: URL", "source-missing")
+  const mimeType = opts.mimeType ?? (m[1] || "application/octet-stream")
+  const data = m[2] ? m[3] : Buffer.from(decodeURIComponent(m[3]), "utf8").toString("base64")
+  return finish(partTypeForMime(mimeType), mimeType, { data }, opts)
+}
+
+/** Keep an `http(s):` URL as a url part; mime comes from the table or an explicit override. */
+export function fromUrl(url: string, opts: AttachOptions = {}): ContentPart {
+  const mimeType = opts.mimeType ?? mediaTypeFor(new URL(url).pathname)?.mimeType
+  if (!mimeType) throw unknownExtension(new URL(url).pathname)
+  return finish(partTypeForMime(mimeType), mimeType, { url }, opts)
+}
+
+function finish(
+  type: "image" | "file" | "audio",
+  mimeType: string,
+  source: { data?: string; url?: string },
+  opts: AttachOptions,
+): ContentPart {
+  const part: any = { type, mimeType, ...source }
+  if (type === "file" && opts.name) part.name = opts.name
+  return validatePart(part as ContentPart, opts.maxPartBytes)
+}
+
+// --------------------------------------------------------------------------- //
+// §8A emission — the positive allowlist, and the unsupported-part rule.
+// --------------------------------------------------------------------------- //
+
+/** The ONLY block types that may reach each style's wire. A part encoding to anything
+ *  else never leaves this module (map-and-hope is how content gets silently discarded). */
+const ALLOWLIST: Record<PartStyle, ReadonlySet<string>> = {
+  openai: new Set(["text", "image_url", "file", "input_audio"]),
+  anthropic: new Set(["text", "image", "document"]),
+}
+
+/** OpenAI's `input_audio.format` is a bare format name, not a mime type. */
+const AUDIO_FORMATS: Record<string, string> = { "audio/mpeg": "mp3", "audio/mp3": "mp3", "audio/wav": "wav", "audio/x-wav": "wav" }
+
+const dataUrl = (mimeType: string, data: string) => `data:${mimeType};base64,${data}`
+
+/**
+ * Encode one part into its provider block, or `undefined` when the style defines no shape
+ * for it. Refusals are explicit, never a fall-through: `openai × file+url` (Chat Completions
+ * has no URL form for a file) and `anthropic × audio` (the provider defines no audio block).
+ */
+export function encodePart(part: ContentPart, style: PartStyle): Record<string, any> | undefined {
+  if (part.type === "text") return { type: "text", text: part.text }
+  if (style === "openai") {
+    switch (part.type) {
+      case "image":
+        return { type: "image_url", image_url: { url: part.data ? dataUrl(part.mimeType, part.data) : part.url } }
+      case "file":
+        // `file_data` REQUIRES the `data:<mime>;base64,` prefix — a bare base64 string is a 400.
+        if (!part.data) return undefined
+        return { type: "file", file: { filename: part.name ?? "file", file_data: dataUrl(part.mimeType, part.data) } }
+      case "audio":
+        if (!part.data) return undefined
+        return { type: "input_audio", input_audio: { data: part.data, format: AUDIO_FORMATS[part.mimeType] ?? part.mimeType.replace(/^audio\//, "") } }
+    }
+  }
+  switch (part.type) {
+    case "image":
+      return part.data
+        ? { type: "image", source: { type: "base64", media_type: part.mimeType, data: part.data } }
+        : { type: "image", source: { type: "url", url: part.url } }
+    case "file":
+      return part.data
+        ? { type: "document", source: { type: "base64", media_type: part.mimeType, data: part.data } }
+        : { type: "document", source: { type: "url", url: part.url } }
+    case "audio":
+      return undefined // Anthropic defines no audio block — a named refusal, not an oversight.
+  }
+}
+
+/** Context for {@link encodeParts}: which wire, who asked for the part, and the override. */
+export interface EncodeOptions {
+  style: PartStyle
+  provenance: PartProvenance
+  onUnsupportedPart?: UnsupportedPartMode
+  maxPartBytes?: number
+}
+
+const warnedUnsupported = new Set<string>()
+
+/** Test seam: forget which unsupported (style, type) pairs have already been warned about. */
+export function resetUnsupportedWarnings(): void {
+  warnedUnsupported.clear()
+}
+
+/** The text a degraded (non-failing) unsupported part leaves behind — never silence. */
+export function unsupportedPlaceholder(part: ContentPart): string {
+  return `[unsupported ${part.type} part (${(part as any).mimeType}, ${partBytes(part)} bytes)]`
+}
+
+/** Warn once per (style, type, reason) — the same latch the unsupported-block path uses,
+ *  keyed separately (by `reason`, not by the message text) so an oversize warning and a
+ *  no-block warning never suppress each other, and a differently-sized oversize part of the
+ *  same type doesn't re-trigger the latch. */
+function warnUnsupportedOnce(style: PartStyle, type: string, reason: "unsupported" | "too-large", message: string): void {
+  const key = `${style}:${type}:${reason}`
+  if (warnedUnsupported.has(key)) return
+  warnedUnsupported.add(key)
+  console.warn(`[toolnexus] ${message}`)
+}
+
+/**
+ * Encode a list of parts for one style, applying the §8A rules:
+ * an **attached** part the style cannot represent raises before any HTTP call; a **derived**
+ * part degrades to a text placeholder and warns once. `onUnsupportedPart` overrides both.
+ * Every emitted block is asserted against the style's allowlist.
+ *
+ * `maxPartBytes` (§1B) is enforced here too, at assembly, over EVERY part regardless of
+ * provenance — a part that arrived from an MCP server never passed through an edge
+ * constructor, so a limit it can walk around is not a limit. Going over follows the exact
+ * same provenance split as an unsupported block: an attached part errors, a derived one
+ * degrades to the placeholder so a remote server still cannot fail the run.
+ */
+export function encodeParts(parts: readonly ContentPart[], opts: EncodeOptions): Record<string, any>[] {
+  const mode: UnsupportedPartMode = opts.onUnsupportedPart ?? (opts.provenance === "attached" ? "error" : "text")
+  const out: Record<string, any>[] = []
+  for (const raw of parts) {
+    const part = validatePart(raw)
+    if (opts.maxPartBytes !== undefined && part.type !== "text") {
+      const bytes = partBytes(part)
+      if (bytes > opts.maxPartBytes) {
+        if (mode === "error") {
+          throw new ContentPartError(
+            `content part "${part.type}" is ${bytes} decoded bytes, over the maxPartBytes limit of ${opts.maxPartBytes}`,
+            "too-large",
+          )
+        }
+        warnUnsupportedOnce(
+          opts.style,
+          part.type,
+          "too-large",
+          `content part "${part.type}" is ${bytes} decoded bytes, over the maxPartBytes limit of ${opts.maxPartBytes} — sending a text placeholder`,
+        )
+        out.push({ type: "text", text: unsupportedPlaceholder(part) })
+        continue
+      }
+    }
+    const block = encodePart(part, opts.style)
+    if (block && ALLOWLIST[opts.style].has(String(block.type))) {
+      out.push(block)
+      continue
+    }
+    if (mode === "error") {
+      throw new ContentPartError(
+        `provider style "${opts.style}" defines no block for a "${part.type}" content part` +
+          (part.type !== "text" ? ` (${part.mimeType})` : ""),
+        "unsupported",
+      )
+    }
+    warnUnsupportedOnce(opts.style, part.type, "unsupported", `provider style "${opts.style}" has no block for a "${part.type}" part — sending a text placeholder`)
+    out.push({ type: "text", text: unsupportedPlaceholder(part) })
+  }
+  return out
+}
+
+/**
+ * Read an inbound OpenAI-shaped content block back into a `ContentPart` (§11). Accepts both
+ * a `ContentPart` written literally and the provider-native block the same part encodes to,
+ * so a caller's own OpenAI messages translate as faithfully as ours do.
+ */
+export function inboundPart(block: unknown): ContentPart | undefined {
+  if (isContentPart(block)) return block
+  if (!block || typeof block !== "object") return undefined
+  const b = block as any
+  if (b.type === "image_url" && b.image_url?.url) {
+    const url = String(b.image_url.url)
+    try {
+      return url.startsWith("data:") ? fromDataUrl(url) : { type: "image", mimeType: mediaTypeFor(new URL(url).pathname)?.mimeType ?? "image/*", url }
+    } catch {
+      return undefined
+    }
+  }
+  if (b.type === "file" && typeof b.file?.file_data === "string") {
+    const part = fromDataUrl(String(b.file.file_data)) as any
+    part.type = "file"
+    if (b.file.filename) part.name = String(b.file.filename)
+    return part as ContentPart
+  }
+  if (b.type === "input_audio" && typeof b.input_audio?.data === "string") {
+    const fmt = String(b.input_audio.format ?? "")
+    const mimeType = fmt === "mp3" ? "audio/mpeg" : fmt === "wav" ? "audio/wav" : `audio/${fmt || "*"}`
+    return { type: "audio", mimeType, data: String(b.input_audio.data) }
+  }
+  return undefined
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+export * from "./content.js"
+export * from "./wire.js"
 export * from "./types.js"
 export * from "./mcp.js"
 export * from "./skill.js"