toolnexus 0.9.5 → 0.12.0

package/dist/client.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Toolkit } from "./toolkit.js";
 import type { ToolResult, Request, Answer } from "./types.js";
+import type { TranslateRequest, TranslateResult } from "./translate.js";
 export type ClientStyle = "openai" | "anthropic";
 export interface ClientOptions {
     baseUrl: string;
@@ -184,10 +185,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(). */
 export type StreamEvent = {
@@ -242,7 +247,8 @@ export declare class Client {
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */
     private emit;
-    /** Emit the terminal `run` metric event and build the 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;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;
@@ -251,6 +257,28 @@ export declare class Client {
         signal?: AbortSignal;
         history?: any[];
     }): Promise<RunResult>;
+    /**
+     * 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.
+     */
+    translate(req: TranslateRequest): Promise<TranslateResult>;
+    /** OpenAI-style upstream: near-passthrough. */
+    private translateOpenAI;
+    /** Anthropic-style upstream: the real translation. */
+    private translateAnthropic;
+    /**
+     * 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[];
     /**
      * 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

package/dist/client.js

@@ -1,4 +1,5 @@
 import { pendingOf } from "./types.js";
+import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
@@ -213,10 +214,11 @@ export class Client {
         this.registry.record(ev);
         this.opts.onMetric?.(ev);
     }
-    /** Emit the terminal `run` metric event and build the RunResult. */
-    endRun(runStart, text, messages, toolCalls, turns, usage) {
+    /** 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). */
+    endRun(runStart, text, messages, toolCalls, turns, usage, exhausted = false) {
         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). */
     emitRunError(runStart, toolCalls, turns, usage, e) {
@@ -227,6 +229,152 @@ export class Client {
             ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
             : 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) {
+        return this.opts.style === "anthropic" ? this.translateAnthropic(req) : this.translateOpenAI(req);
+    }
+    /** OpenAI-style upstream: near-passthrough. */
+    async translateOpenAI(req) {
+        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 = { 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 = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            addUsage(usage, data.usage, "openai");
+            const choice = data.choices?.[0];
+            const toolCalls = (choice?.message?.tool_calls ?? []).map((tc) => ({
+                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. */
+    async translateAnthropic(req) {
+        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 = {
+            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 = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            addUsage(usage, data.usage, "anthropic");
+            const text = [];
+            const toolCalls = [];
+            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) {
+        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
@@ -436,15 +584,19 @@ export class Client {
                         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;
         }
     }
-    result(text, messages, toolCalls, turns, usage) {
-        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" };
+    result(text, messages, toolCalls, turns, usage, exhausted = false) {
+        const incomplete = exhausted && text === "";
+        const r = { 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. */
     pendingRun(runStart, request, messages, toolCalls, turns, usage) {
@@ -545,7 +697,7 @@ export class Client {
                 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);
@@ -655,7 +807,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);
@@ -764,7 +916,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);

package/dist/index.d.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/dist/index.js

@@ -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/dist/translate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 declare function finishReasonFor(hasToolCalls: boolean, providerStop?: string): TranslateResult["finishReason"];
+/** Flattens an OpenAI `content` value to text: the string form and the parts-array form. */
+export declare function contentText(content: unknown): string;
+/** Parses a tool-call arguments value into an object, tolerating both wire forms. */
+export declare function argsObject(args: unknown): Record<string, unknown>;
+/** Renders a tool-call arguments value as the JSON string the OpenAI wire format uses. */
+export declare function argsString(args: unknown): string;
+/** Reads an assistant message's OpenAI `tool_calls`. */
+export declare function toolCallsOf(m: any): TranslatedToolCall[];
+/**
+ * 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 declare function openAIMessagesToAnthropic(messages: any[]): {
+    messages: any[];
+    system: string;
+};
+/**
+ * Converts an OpenAI `tools` array into Anthropic tool declarations. Entries that are
+ * already provider-native pass through; anything unrecognized is skipped.
+ */
+export declare function openAIToolsToAnthropic(tools: any[] | undefined): any[];
+/**
+ * Maps OpenAI `tool_choice` onto Anthropic's shape. Returns undefined for absent/"auto"
+ * (the provider default) and for anything unrecognized.
+ */
+export declare function openAIToolChoiceToAnthropic(choice: unknown): any;
+/** True when the message list already carries a system-ish message. */
+export declare function hasSystemMessage(messages: any[]): boolean;

package/dist/translate.js

@@ -0,0 +1,195 @@
+/**
+ * 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.
+ */
+/**
+ * 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, providerStop) {
+    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) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((p) => (p && typeof p === "object" && typeof p.text === "string" ? p.text : ""))
+            .join("");
+    }
+    return "";
+}
+/** Parses a tool-call arguments value into an object, tolerating both wire forms. */
+export function argsObject(args) {
+    if (args && typeof args === "object")
+        return args;
+    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) {
+    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) {
+    const raw = m?.tool_calls;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    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) {
+    const out = [];
+    const systemParts = [];
+    let pendingResults = [];
+    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 = { 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 = [];
+                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) {
+    const out = [];
+    for (const t of tools ?? []) {
+        if (!t || typeof t !== "object")
+            continue;
+        const fn = t.function;
+        if (!fn) {
+            if (t.name)
+                out.push(t); // already native
+            continue;
+        }
+        if (!fn.name)
+            continue;
+        const decl = { 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) {
+    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.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) {
+    return (messages ?? []).some((m) => m?.role === "system" || m?.role === "developer");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.9.5",
+  "version": "0.12.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/home.test.ts test/compaction.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [