toolnexus 0.9.5 → 0.12.0

package/src/client.ts

@@ -6,6 +6,16 @@
 import type { Toolkit } from "./toolkit.js"
 import type { ToolResult, Request, Answer } from "./types.js"
 import { pendingOf } from "./types.js"
+import type { TranslateRequest, TranslateResult, TranslatedToolCall } from "./translate.js"
+import {
+  finishReasonFor,
+  contentText,
+  argsString,
+  openAIMessagesToAnthropic,
+  openAIToolsToAnthropic,
+  openAIToolChoiceToAnthropic,
+  hasSystemMessage,
+} from "./translate.js"
 
 export type ClientStyle = "openai" | "anthropic"
 
@@ -155,10 +165,14 @@ export interface RunResult {
   usage: Usage
   /** The model used. */
   model: string
-  /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
-  status: "done" | "pending"
+  /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10);
+   * "incomplete" iff a limit stopped the run loudly (§7D) — a maxTurns stop with no final
+   * text is never a silent "done". */
+  status: "done" | "pending" | "incomplete"
   /** The unresolved suspension — present iff status === "pending" (§10). */
   pending?: Request
+  /** The limit that stopped the run (e.g. "maxTurns") — present iff status === "incomplete". */
+  limit?: string
 }
 
 /** Events yielded by client.stream(). */
@@ -379,10 +393,11 @@ export class Client {
     this.opts.onMetric?.(ev)
   }
 
-  /** Emit the terminal `run` metric event and build the RunResult. */
-  private endRun(runStart: number, text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
+  /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
+   * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
+  private endRun(runStart: number, text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage, exhausted = false): RunResult {
     this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart })
-    return this.result(text, messages, toolCalls, turns, usage)
+    return this.result(text, messages, toolCalls, turns, usage, exhausted)
   }
 
   /** Emit a `run` error metric event (once, on a thrown run). */
@@ -396,6 +411,159 @@ export class Client {
       : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history)
   }
 
+  /**
+   * Single-turn translation (§11): exactly ONE provider call, returned in OpenAI shape.
+   * No agent loop, no tool execution, no conversation state — every call is
+   * self-contained, so this may be run statelessly and concurrently.
+   *
+   * The inbound half of the adapters: `toAnthropic`/`toGemini` send declarations out,
+   * this reads the provider's tool calls back in. A `toolkit` passed in the request is
+   * DECLARED and never executed.
+   *
+   * Retries/backoff, requestParams merging and the `llm` metric are shared with the loop.
+   * `beforeLLM`/`afterLLM` fire once; tool hooks do not, because no tool runs.
+   */
+  async translate(req: TranslateRequest): Promise<TranslateResult> {
+    return this.opts.style === "anthropic" ? this.translateAnthropic(req) : this.translateOpenAI(req)
+  }
+
+  /** OpenAI-style upstream: near-passthrough. */
+  private async translateOpenAI(req: TranslateRequest): Promise<TranslateResult> {
+    const key = resolveKey(this.opts)
+    const declared = [...(req.toolkit ? req.toolkit.toOpenAI() : []), ...(req.tools ?? [])]
+    let messages = (req.messages ?? []).slice()
+    const sys = req.system ?? this.opts.systemPrompt ?? ""
+    if (sys && !hasSystemMessage(messages)) messages = [{ role: "system", content: sys }, ...messages]
+
+    let tools = declared
+    if (this.opts.hooks?.beforeLLM) {
+      const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 })
+      if (ov?.messages) messages = ov.messages
+      if (ov?.tools) tools = ov.tools
+    }
+
+    const body: Record<string, any> = { model: this.opts.model, messages }
+    if (tools.length) body.tools = tools
+    if (req.toolChoice !== undefined) body.tool_choice = req.toolChoice
+    if (req.maxTokens) body.max_tokens = req.maxTokens
+
+    const signal = this.makeSignal(req.signal)
+    {
+      const data = await this.llmCallJson(
+        `${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json", authorization: `Bearer ${key}`, ...this.opts.headers },
+          body: JSON.stringify(this.finalizeBody(body)),
+        },
+        signal,
+        "openai",
+      )
+      if (this.opts.hooks?.afterLLM) await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 })
+      const usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      addUsage(usage, data.usage, "openai")
+      const choice = data.choices?.[0]
+      const toolCalls: TranslatedToolCall[] = (choice?.message?.tool_calls ?? []).map((tc: any) => ({
+        id: String(tc.id ?? ""),
+        name: String(tc.function?.name ?? ""),
+        arguments: argsString(tc.function?.arguments),
+      }))
+      return {
+        text: choice?.message?.content ?? "",
+        toolCalls,
+        finishReason: choice?.finish_reason ?? finishReasonFor(toolCalls.length > 0),
+        usage,
+        model: this.opts.model,
+        raw: data,
+      }
+    }
+  }
+
+  /** Anthropic-style upstream: the real translation. */
+  private async translateAnthropic(req: TranslateRequest): Promise<TranslateResult> {
+    const key = resolveKey(this.opts)
+    const base = this.opts.baseUrl.replace(/\/$/, "")
+    const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`
+
+    const converted = openAIMessagesToAnthropic(req.messages ?? [])
+    let messages = converted.messages
+    const system = req.system ?? this.opts.systemPrompt ?? converted.system
+    let tools = [
+      ...(req.toolkit ? req.toolkit.toAnthropic() : []),
+      ...openAIToolsToAnthropic(req.tools),
+    ]
+
+    if (this.opts.hooks?.beforeLLM) {
+      const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 })
+      if (ov?.messages) messages = ov.messages
+      if (ov?.tools) tools = ov.tools
+    }
+
+    const body: Record<string, any> = {
+      model: this.opts.model,
+      max_tokens: req.maxTokens && req.maxTokens > 0 ? req.maxTokens : 4096,
+      messages,
+    }
+    if (system) body.system = system
+    if (tools.length) body.tools = tools
+    const tc = openAIToolChoiceToAnthropic(req.toolChoice)
+    if (tc) body.tool_choice = tc
+
+    const signal = this.makeSignal(req.signal)
+    {
+      const data = await this.llmCallJson(
+        endpoint,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+            ...this.opts.headers,
+          },
+          body: JSON.stringify(this.finalizeBody(body)),
+        },
+        signal,
+        "anthropic",
+      )
+      if (this.opts.hooks?.afterLLM) await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 })
+      const usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      addUsage(usage, data.usage, "anthropic")
+      const text: string[] = []
+      const toolCalls: TranslatedToolCall[] = []
+      for (const b of data.content ?? []) {
+        if (b?.type === "text") text.push(b.text ?? "")
+        else if (b?.type === "tool_use") {
+          toolCalls.push({
+            id: String(b.id ?? ""),
+            name: String(b.name ?? ""),
+            arguments: JSON.stringify(b.input ?? {}),
+          })
+        }
+      }
+      return {
+        text: text.join(""),
+        toolCalls,
+        finishReason: finishReasonFor(toolCalls.length > 0, data.stop_reason),
+        usage,
+        model: this.opts.model,
+        raw: data,
+      }
+    }
+  }
+
+  /**
+   * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
+   * on an assistant message. Convenience for assembling a response envelope.
+   */
+  static toolCallsJSON(res: TranslateResult): any[] {
+    return res.toolCalls.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: { name: tc.name, arguments: tc.arguments },
+    }))
+  }
+
   /**
    * Stateful ask. With an `id`, the client's `store` remembers the conversation:
    * it loads that id's transcript, runs, saves the updated transcript, and returns
@@ -596,15 +764,18 @@ export class Client {
           if (s.halted) return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage)
         }
       }
-      return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage)
+      return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true)
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e
     }
   }
 
-  private result(text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
-    return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" }
+  private result(text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage, exhausted = false): RunResult {
+    const incomplete = exhausted && text === ""
+    const r: RunResult = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: incomplete ? "incomplete" : "done" }
+    if (incomplete) r.limit = "maxTurns"
+    return r
   }
 
   /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
@@ -702,7 +873,7 @@ export class Client {
         messages.push({ role: "user", content })
         if (halted) return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage)
       }
-      return this.endRun(runStart, "", messages, toolCalls, turns, usage)
+      return this.endRun(runStart, "", messages, toolCalls, turns, usage, true)
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e
@@ -798,7 +969,7 @@ export class Client {
           yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError }
         }
       }
-      yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage) }
+      yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true) }
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e
@@ -891,7 +1062,7 @@ export class Client {
         }
         messages.push({ role: "user", content: results })
       }
-      yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage) }
+      yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage, true) }
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e

package/src/index.ts

@@ -8,5 +8,7 @@ export * from "./a2a.js"
 export * from "./serve.js"
 export * from "./mcpserve.js"
 export * from "./adapters.js"
+export * from "./translate.js"
 export * from "./toolkit.js"
 export * from "./client.js"
+export * as agents from "./agents/index.js"

package/src/translate.ts

@@ -0,0 +1,242 @@
+/**
+ * Single-turn translation — the translator path (SPEC.md §11, ADR-0011).
+ *
+ * `client.translate(request)` is toolnexus used as a pure wire-format translator: OpenAI
+ * shapes in, exactly ONE provider call, OpenAI shapes out. No agent loop, no tool
+ * execution, no conversation state — so a caller can run it statelessly.
+ *
+ * It is the INBOUND half of the §5 adapters: `toOpenAI`/`toAnthropic`/`toGemini` send
+ * declarations out, this reads the provider's tool calls back in.
+ *
+ * Use it when the CALLER owns the conversation and executes tools itself (the standard
+ * OpenAI function-calling posture). When toolnexus owns the conversation, use the agent
+ * loop with relay tools + `runWithAnswer` (§10) instead.
+ */
+
+import type { Toolkit } from "./toolkit.js"
+import type { Usage } from "./client.js"
+
+/** An OpenAI-shaped chat request, handed over verbatim (§11). */
+export interface TranslateRequest {
+  /**
+   * The OpenAI `messages` array, verbatim — including assistant turns carrying
+   * `tool_calls` and `tool`-role results carrying `tool_call_id`.
+   */
+  messages: any[]
+  /**
+   * The OpenAI `tools` array, verbatim
+   * (`{type:"function",function:{name,description,parameters}}`). Declaration-only —
+   * nothing here is ever executed.
+   */
+  tools?: any[]
+  /**
+   * Declares an ordinary toolkit's tools to the provider WITHOUT executing any of them —
+   * MCP tools, skills, native functions, A2A agents, builtins. Use this when you have a
+   * toolkit and want the model's tool CALLS handed back to you to dispatch yourself.
+   * Composes with `tools`; toolkit declarations come first.
+   */
+  toolkit?: Toolkit
+  /** The OpenAI `tool_choice`, verbatim. Omitted when absent. */
+  toolChoice?: any
+  /** Overrides the system prompt. Absent uses any `system` message found in `messages`. */
+  system?: string
+  /** Overrides the per-provider default max tokens. */
+  maxTokens?: number
+  /** Aborts the in-flight provider call. */
+  signal?: AbortSignal
+}
+
+/** One tool call the model asked for, in OpenAI shape (§11). */
+export interface TranslatedToolCall {
+  /** The tool-call id the caller must echo on its `tool` result message. */
+  id: string
+  /** The function name. */
+  name: string
+  /** Arguments as a JSON **string** — the OpenAI wire form, echoable byte-for-byte. */
+  arguments: string
+}
+
+/** An OpenAI-shaped single-turn result (§11). */
+export interface TranslateResult {
+  /** Assistant text ("" when the model only called tools). */
+  text: string
+  /** The tool calls the model emitted, in provider order. None is ever dropped. */
+  toolCalls: TranslatedToolCall[]
+  /** The OpenAI finish reason. A turn with any tool call is always `"tool_calls"`. */
+  finishReason: "stop" | "tool_calls" | "length" | "content_filter"
+  /** This single call's token usage. */
+  usage: Usage
+  /** The model that answered. */
+  model: string
+  /** The provider's decoded response, for fields this type does not model. */
+  raw?: any
+}
+
+/**
+ * Maps a provider stop reason onto an OpenAI finish reason. Tool calls win: a turn that
+ * emitted any tool call is always `"tool_calls"` to a conforming client.
+ */
+export function finishReasonFor(hasToolCalls: boolean, providerStop?: string): TranslateResult["finishReason"] {
+  if (hasToolCalls) return "tool_calls"
+  switch (providerStop) {
+    case "max_tokens":
+    case "length":
+      return "length"
+    case "refusal":
+    case "content_filter":
+      return "content_filter"
+    default:
+      return "stop"
+  }
+}
+
+/** Flattens an OpenAI `content` value to text: the string form and the parts-array form. */
+export function contentText(content: unknown): string {
+  if (typeof content === "string") return content
+  if (Array.isArray(content)) {
+    return content
+      .map((p) => (p && typeof p === "object" && typeof (p as any).text === "string" ? (p as any).text : ""))
+      .join("")
+  }
+  return ""
+}
+
+/** Parses a tool-call arguments value into an object, tolerating both wire forms. */
+export function argsObject(args: unknown): Record<string, unknown> {
+  if (args && typeof args === "object") return args as Record<string, unknown>
+  if (typeof args === "string" && args.trim()) {
+    try {
+      const parsed = JSON.parse(args)
+      if (parsed && typeof parsed === "object") return parsed
+    } catch {
+      /* fall through to {} — a malformed arguments string is not fatal */
+    }
+  }
+  return {}
+}
+
+/** Renders a tool-call arguments value as the JSON string the OpenAI wire format uses. */
+export function argsString(args: unknown): string {
+  if (typeof args === "string") return args
+  if (args && typeof args === "object") return JSON.stringify(args)
+  return "{}"
+}
+
+/** Reads an assistant message's OpenAI `tool_calls`. */
+export function toolCallsOf(m: any): TranslatedToolCall[] {
+  const raw = m?.tool_calls
+  if (!Array.isArray(raw)) return []
+  const out: TranslatedToolCall[] = []
+  for (const tc of raw) {
+    const fn = tc?.function
+    if (!fn) continue
+    out.push({ id: String(tc.id ?? ""), name: String(fn.name ?? ""), arguments: argsString(fn.arguments) })
+  }
+  return out
+}
+
+/**
+ * Converts an OpenAI `messages` array into Anthropic-native messages plus the extracted
+ * system prompt, preserving the tool structure a text flattening destroys (§11):
+ *
+ * - an assistant turn's `tool_calls` become `tool_use` blocks (arguments re-parsed to objects),
+ * - a `tool`-role result becomes a `tool_result` block keyed by `tool_call_id`, MERGED into a
+ *   single user turn when consecutive (providers want one result-bearing turn per assistant turn),
+ * - `system`/`developer` messages are hoisted out, since Anthropic takes system separately.
+ */
+export function openAIMessagesToAnthropic(messages: any[]): { messages: any[]; system: string } {
+  const out: any[] = []
+  const systemParts: string[] = []
+  let pendingResults: any[] = []
+
+  const flush = () => {
+    if (pendingResults.length) {
+      out.push({ role: "user", content: pendingResults })
+      pendingResults = []
+    }
+  }
+
+  for (const m of messages ?? []) {
+    if (!m || typeof m !== "object") continue
+    switch (m.role) {
+      case "system":
+      case "developer": {
+        flush()
+        const s = contentText(m.content)
+        if (s) systemParts.push(s)
+        break
+      }
+      case "tool":
+      case "function": {
+        const block: any = { type: "tool_result", content: contentText(m.content) }
+        if (m.tool_call_id) block.tool_use_id = String(m.tool_call_id)
+        pendingResults.push(block)
+        break
+      }
+      case "assistant": {
+        flush()
+        const blocks: any[] = []
+        const s = contentText(m.content)
+        if (s) blocks.push({ type: "text", text: s })
+        for (const tc of toolCallsOf(m)) {
+          blocks.push({ type: "tool_use", id: tc.id, name: tc.name, input: argsObject(tc.arguments) })
+        }
+        if (!blocks.length) break // an empty assistant turn would be rejected
+        out.push({ role: "assistant", content: blocks })
+        break
+      }
+      default: {
+        flush()
+        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 })
+      }
+    }
+  }
+  flush()
+  return { messages: out, system: systemParts.join("\n\n") }
+}
+
+/**
+ * Converts an OpenAI `tools` array into Anthropic tool declarations. Entries that are
+ * already provider-native pass through; anything unrecognized is skipped.
+ */
+export function openAIToolsToAnthropic(tools: any[] | undefined): any[] {
+  const out: any[] = []
+  for (const t of tools ?? []) {
+    if (!t || typeof t !== "object") continue
+    const fn = (t as any).function
+    if (!fn) {
+      if ((t as any).name) out.push(t) // already native
+      continue
+    }
+    if (!fn.name) continue
+    const decl: any = { name: fn.name }
+    if (fn.description) decl.description = fn.description
+    decl.input_schema = fn.parameters ?? { type: "object", properties: {} }
+    out.push(decl)
+  }
+  return out
+}
+
+/**
+ * Maps OpenAI `tool_choice` onto Anthropic's shape. Returns undefined for absent/"auto"
+ * (the provider default) and for anything unrecognized.
+ */
+export function openAIToolChoiceToAnthropic(choice: unknown): any {
+  if (typeof choice === "string") {
+    if (choice === "required" || choice === "any") return { type: "any" }
+    if (choice === "none") return { type: "none" }
+    return undefined
+  }
+  if (choice && typeof choice === "object") {
+    const name = (choice as any).function?.name
+    if (name) return { type: "tool", name }
+  }
+  return undefined
+}
+
+/** True when the message list already carries a system-ish message. */
+export function hasSystemMessage(messages: any[]): boolean {
+  return (messages ?? []).some((m) => m?.role === "system" || m?.role === "developer")
+}