toolnexus 0.16.0 → 0.18.0

package/src/translate.ts

@@ -14,6 +14,7 @@
  */
 
 import type { Toolkit } from "./toolkit.js"
+import { encodeParts, inboundPart, type ContentPart } from "./content.js"
 import type { Usage } from "./client.js"
 
 /** An OpenAI-shaped chat request, handed over verbatim (§11). */
@@ -187,9 +188,14 @@ export function openAIMessagesToAnthropic(messages: any[]): { messages: any[]; s
       }
       default: {
         flush()
+        // A `content` array has its text parts concatenated and its NON-text parts translated
+        // into Anthropic's block shape (§11). Six ports used to pass a text-empty array through
+        // raw and undocumented; one specified mapping replaces that, so nothing is flattened
+        // away and nothing is dropped.
+        const blocks = contentPartBlocks(m.content)
+        if (blocks) { out.push({ role: "user", content: blocks }); break }
         const s = contentText(m.content)
         if (s) out.push({ role: "user", content: s })
-        else if (Array.isArray(m.content) && m.content.length) out.push({ role: "user", content: m.content })
       }
     }
   }
@@ -197,6 +203,24 @@ export function openAIMessagesToAnthropic(messages: any[]): { messages: any[]; s
   return { messages: out, system: systemParts.join("\n\n") }
 }
 
+/**
+ * Translate an OpenAI-shaped `content` array into Anthropic blocks — but ONLY when it
+ * actually carries something non-text; an all-text array still concatenates, so the
+ * common case is byte-identical. Both spellings are accepted: a literal `ContentPart`
+ * and the provider-native block that same part encodes to.
+ */
+function contentPartBlocks(content: unknown): any[] | undefined {
+  if (!Array.isArray(content) || content.length === 0) return undefined
+  const parts: ContentPart[] = []
+  for (const raw of content) {
+    const p = inboundPart(raw)
+    if (!p) return undefined // an array we do not understand is left to contentText, as before
+    parts.push(p)
+  }
+  if (parts.every((p) => p.type === "text")) return undefined
+  return encodeParts(parts, { style: "anthropic", provenance: "attached" })
+}
+
 /**
  * Converts an OpenAI `tools` array into Anthropic tool declarations. Entries that are
  * already provider-native pass through; anything unrecognized is skipped.

package/src/types.ts

@@ -10,11 +10,20 @@ export type JSONSchema = {
   [k: string]: unknown
 }
 
+import type { ContentPart } from "./content.js"
+
 export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "custom"
 
 export interface ToolResult {
   output: string
   isError: boolean
+  /**
+   * §1B non-text output. `output` stays required and remains what the transcript,
+   * compaction, token estimation and any text-only provider see; `parts` is the extra
+   * channel a screenshot / PDF / audio clip travels on. Absent ⇒ byte-identical to a
+   * pre-0.17 result, which is why it is optional rather than a fourth required field.
+   */
+  parts?: ContentPart[]
   metadata?: Record<string, unknown>
 }
 

package/src/wire.ts

@@ -0,0 +1,131 @@
+/**
+ * Canonical transcript → provider wire messages (SPEC.md §8A).
+ *
+ * The loop's `messages` array is the **canonical transcript**: a user turn carrying parts
+ * holds `ContentPart[]`, and a tool turn carrying parts holds them under a `parts` key.
+ * Neither shape is a wire shape. This module is the single place that turns the canonical
+ * transcript into what each style actually accepts, so the four loop sites (run/stream ×
+ * openai/anthropic) only ever have to *record* parts, never encode them.
+ *
+ * It is also where the **tool-result relocation rule** lives. Anthropic defines blocks
+ * inside `tool_result.content`, so its parts are emitted natively, keyed to their
+ * `tool_use_id`. OpenAI's `tool` message rejects an image outright (a hard 400 — "Image URLs
+ * are only allowed for messages with role 'user'"), so there every non-text part from every
+ * tool result answering one assistant turn is relocated, in tool-call order, into ONE
+ * synthetic `user` message emitted immediately after the last tool message. That synthetic
+ * message is an adapter artifact: it is built here, on the way out, and never written back
+ * to the transcript, the `ConversationStore` or `translate` output — which is what keeps a
+ * mid-conversation provider switch free of OpenAI-shaped residue.
+ */
+import type { ContentPart, PartStyle, UnsupportedPartMode } from "./content.js"
+import { encodeParts, isContentPart, validatePart } from "./content.js"
+
+/** Shared shaping options for a wire build. */
+export interface WireOptions {
+  onUnsupportedPart?: UnsupportedPartMode
+  maxPartBytes?: number
+}
+
+/** The text preceding each relocated part, so the model can attribute it to its call. */
+export const relocationHeader = (name: string, id: string) => `Output of tool ${name} (${id}):`
+
+/** Split parts into the text ones (which ride along in place) and the rest. */
+function split(parts: readonly ContentPart[]): { texts: ContentPart[]; others: ContentPart[] } {
+  const texts: ContentPart[] = []
+  const others: ContentPart[] = []
+  for (const p of parts) (p.type === "text" ? texts : others).push(p)
+  return { texts, others }
+}
+
+function partsOf(m: any): ContentPart[] | undefined {
+  const p = m?.parts
+  return Array.isArray(p) && p.length ? (p as ContentPart[]) : undefined
+}
+
+/** True when a message's `content` is a canonical `ContentPart[]` rather than a wire array. */
+function isPartArray(content: unknown): content is ContentPart[] {
+  return Array.isArray(content) && content.length > 0 && content.every(isContentPart)
+}
+
+/**
+ * Build the OpenAI-style wire messages. Tool messages carry `output` plus text parts only;
+ * their non-text parts are collected and flushed as one synthetic user message the moment
+ * the run of tool messages ends.
+ */
+export function toOpenAIWire(messages: any[], opts: WireOptions = {}): any[] {
+  const out: any[] = []
+  let relocated: { name: string; id: string; parts: ContentPart[] }[] = []
+
+  const flush = () => {
+    if (!relocated.length) return
+    const blocks: any[] = []
+    for (const r of relocated) {
+      blocks.push({ type: "text", text: relocationHeader(r.name, r.id) })
+      blocks.push(...encodeParts(r.parts, { style: "openai", provenance: "derived", ...opts }))
+    }
+    relocated = []
+    out.push({ role: "user", content: blocks })
+  }
+
+  for (const m of messages ?? []) {
+    if (m?.role === "tool") {
+      const parts = partsOf(m)
+      const { parts: _drop, ...rest } = m ?? {}
+      if (!parts) {
+        out.push(m)
+        continue
+      }
+      const { texts, others } = split(parts)
+      const msg: any = { ...rest }
+      if (texts.length) {
+        msg.content = [{ type: "text", text: String(rest.content ?? "") }, ...encodeParts(texts, { style: "openai", provenance: "derived", ...opts })]
+      }
+      out.push(msg)
+      if (others.length) relocated.push({ name: String(rest.name ?? ""), id: String(rest.tool_call_id ?? ""), parts: others })
+      continue
+    }
+    flush()
+    if (isPartArray(m?.content)) {
+      out.push({ ...m, content: encodeParts(m.content, { style: "openai", provenance: "attached", ...opts }) })
+      continue
+    }
+    out.push(m)
+  }
+  flush()
+  return out
+}
+
+/**
+ * Build the Anthropic-style wire messages. Nothing is relocated: a `tool_result` block that
+ * carries parts gets them natively inside its own `content`, keyed to its `tool_use_id`.
+ */
+export function toAnthropicWire(messages: any[], opts: WireOptions = {}): any[] {
+  return (messages ?? []).map((m) => {
+    if (isPartArray(m?.content)) {
+      return { ...m, content: encodeParts(m.content, { style: "anthropic", provenance: "attached", ...opts }) }
+    }
+    if (!Array.isArray(m?.content)) return m
+    let touched = false
+    const content = m.content.map((block: any) => {
+      if (block?.type !== "tool_result") return block
+      const parts = partsOf(block)
+      if (!parts) return block
+      touched = true
+      const { parts: _drop, ...rest } = block
+      return {
+        ...rest,
+        content: [
+          { type: "text", text: String(rest.content ?? "") },
+          ...encodeParts(parts, { style: "anthropic", provenance: "derived", ...opts }),
+        ],
+      }
+    })
+    return touched ? { ...m, content } : m
+  })
+}
+
+/** Validate every attached part before assembly, so `maxPartBytes` cannot be bypassed. */
+export function checkPromptParts(prompt: unknown, opts: WireOptions): void {
+  if (!Array.isArray(prompt)) return
+  for (const p of prompt) validatePart(p as ContentPart, opts.maxPartBytes)
+}