Add OpenAI tool calling to the chat service

CMakeLists.txt

@@ -122,6 +122,11 @@ if(BUILD_TESTING)
     target_compile_features(ling3-chat-protocol-test PRIVATE cxx_std_20)
     target_include_directories(ling3-chat-protocol-test PRIVATE include third_party/nlohmann)
     add_test(NAME ling3-chat-protocol-test COMMAND ling3-chat-protocol-test)
+    add_executable(ling3-chat-tools-test tests/chat_tools_test.cpp)
+    target_compile_features(ling3-chat-tools-test PRIVATE cxx_std_20)
+    target_include_directories(ling3-chat-tools-test PRIVATE include third_party/nlohmann)
+    add_test(NAME ling3-chat-tools-test COMMAND ling3-chat-tools-test
+             ${CMAKE_CURRENT_SOURCE_DIR}/tests/chat_tools_golden.json)
     add_executable(ling3-router-test tests/router_test.cpp)
     target_link_libraries(ling3-router-test PRIVATE ling3_core)
     add_test(NAME ling3-router-test COMMAND ling3-router-test)

include/ling3/chat_protocol.h

@@ -3,14 +3,20 @@
 #include <nlohmann/json.hpp>
 #include <algorithm>
 #include <cmath>
+#include <cctype>
 #include <cstdint>
+#include <functional>
 #include <limits>
 #include <stdexcept>
 #include <string>
+#include <string_view>
+#include <utility>
 #include <vector>
 
 namespace ling3::chat {
 using Json = nlohmann::json;
+// Request bodies keep key order: the template renders tools as the client sent them.
+using OrderedJson = nlohmann::ordered_json;
 inline constexpr const char * kModel = "mindnano-ling3-tiny";
 struct Error : std::runtime_error {
     int status;
@@ -36,6 +42,8 @@ struct Request {
     bool enable_thinking = false, flow_ack = false;
     std::uint32_t seed = 0;
     std::vector<std::string> stops;
+    OrderedJson tools = OrderedJson::array();
+    bool tool_calls = false, parallel_tool_calls = true; // parse calls from the output
 };
 inline std::size_t OutputBudget(std::size_t prompt, std::size_t capacity,
                                 std::size_t requested) {
@@ -44,14 +52,43 @@ inline std::size_t OutputBudget(std::size_t prompt, std::size_t capacity,
                     std::to_string(capacity) + " tokens, or is empty");
     return std::min(requested, capacity - prompt);
 }
-inline Request Parse(const Json & j) {
+// The template's tojson filter is Python json.dumps(ensure_ascii=False):
+// ", " and ": " separators, keys in the order the client sent them.
+inline std::string TemplateJson(const OrderedJson & v) {
+    if (!v.is_object() && !v.is_array()) return v.dump();
+    std::string s = v.is_object() ? "{" : "[";
+    for (auto it = v.begin(); it != v.end(); ++it) {
+        if (it != v.begin()) s += ", ";
+        if (v.is_object()) s += OrderedJson(it.key()).dump() + ": ";
+        s += TemplateJson(*it);
+    }
+    return s + (v.is_object() ? "}" : "]");
+}
+inline constexpr const char * kToolsHeader = "# Tools\n\nYou may call one or more functions to assist "
+    "with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>";
+inline constexpr const char * kToolsFooter = "\n</tools>\n\nIf none of the functions can be used, point it "
+    "out. If the given question lacks the parameters required by the function, also point it out.\nIf you need "
+    "to use a function, for each function call, output the function name and arguments within the following XML "
+    "format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n"
+    "<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\n";
+struct ToolCall { std::string name; OrderedJson arguments = OrderedJson::object(); };
+// String values are raw text and others JSON, exactly as the template renders history.
+inline std::string RenderToolCall(const ToolCall & call) {
+    std::string s = "<tool_call>" + call.name + "\n";
+    for (auto it = call.arguments.begin(); it != call.arguments.end(); ++it)
+        s += "<arg_key>" + it.key() + "</arg_key>\n<arg_value>" +
+             (it->is_string() ? it->get<std::string>() : TemplateJson(*it)) + "</arg_value>";
+    return s + "\n</tool_call>";
+}
+inline Request Parse(const OrderedJson & j) {
     auto fail = [](std::string m) { throw Error(400, "invalid_parameter", std::move(m)); };
     if (!j.is_object()) fail("request must be a JSON object");
     for (auto it = j.begin(); it != j.end(); ++it) {
         const std::vector<std::string> supported {"model", "messages", "max_tokens",
             "max_completion_tokens", "stream", "stream_options", "temperature", "top_p",
             "seed", "stop", "n", "user", "cache_prompt", "top_k", "repeat_penalty",
-            "enable_thinking", "flow_control", "session_id", "reuse_generated_state"};
+            "enable_thinking", "flow_control", "session_id", "reuse_generated_state",
+            "tools", "tool_choice", "parallel_tool_calls", "store"};
         if (std::find(supported.begin(), supported.end(), it.key()) == supported.end())
             fail("unsupported parameter: " + it.key());
     }
@@ -131,10 +168,12 @@ inline Request Parse(const Json & j) {
         r.seed = j["seed"].get<std::uint32_t>();
     }
     if (j.contains("n") && (!j["n"].is_number_integer() || j["n"] != 1)) fail("only n=1 is supported");
+    // Agent clients send OpenAI's store flag; this server never stores completions.
+    if (j.contains("store") && !j["store"].is_boolean()) fail("store must be boolean");
     if (j.contains("user") && !j["user"].is_string()) fail("user must be a string");
     if (j.contains("user")) r.cache_user = j["user"].get<std::string>();
     if (j.contains("stop") && !j["stop"].is_null()) {
-        const auto s = j["stop"].is_string() ? Json::array({j["stop"]}) : j["stop"];
+        const auto s = j["stop"].is_string() ? OrderedJson::array({j["stop"]}) : j["stop"];
         if (!s.is_array() || s.size() > 4) fail("stop must be a string or at most 4 strings");
         for (const auto & v : s) {
             if (!v.is_string() || v.get_ref<const std::string &>().empty() ||
@@ -142,59 +181,133 @@ inline Request Parse(const Json & j) {
             r.stops.push_back(v.get<std::string>());
         }
     }
+    if (j.contains("tools") && !j["tools"].is_null()) {
+        if (!j["tools"].is_array()) fail("tools must be an array");
+        for (const auto & t : j["tools"])
+            if (!t.is_object() || !t.contains("type") || t["type"] != "function" || !t.contains("function") ||
+                !t["function"].is_object() || !t["function"].contains("name") || !t["function"]["name"].is_string() ||
+                t["function"]["name"].get_ref<const std::string &>().empty())
+                fail("tools must be named function tools");
+        r.tools = j["tools"];
+    }
+    // Calls are parsed after generation, so only auto and none can be honored.
+    const bool no_tool_choice = !j.contains("tool_choice") || j["tool_choice"].is_null();
+    if (!no_tool_choice && j["tool_choice"] != "auto" && j["tool_choice"] != "none")
+        fail("tool_choice must be auto or none");
+    if (j.contains("parallel_tool_calls")) {
+        if (!j["parallel_tool_calls"].is_boolean()) fail("parallel_tool_calls must be boolean");
+        r.parallel_tool_calls = j["parallel_tool_calls"].get<bool>();
+    }
+    r.tool_calls = !r.tools.empty() && (no_tool_choice || j["tool_choice"] == "auto");
     if (!j.contains("messages") || !j["messages"].is_array() || j["messages"].empty())
         fail("messages must be a non-empty array");
-    const auto & messages = j["messages"];
-    for (const auto & m : messages) {
-        if (!m.is_object() || !m.contains("role") || !m["role"].is_string() ||
-            !m.contains("content") || !m["content"].is_string())
-            fail("messages require string role and content; text only");
-        const auto role = m["role"].get<std::string>();
-        if (role != "system" && role != "user" && role != "assistant") fail("unsupported message role");
+    struct Message { std::string role, content, reasoning; std::vector<ToolCall> calls; };
+    std::vector<Message> messages;
+    for (const auto & m : j["messages"]) {
+        if (!m.is_object() || !m.contains("role") || !m["role"].is_string()) fail("messages require a string role");
+        Message message {m["role"].get<std::string>()};
+        const auto & role = message.role;
+        if (role != "system" && role != "user" && role != "assistant" && role != "tool") fail("unsupported message role");
+        std::vector<std::string> fields {"role", "content"};
+        if (role == "assistant") fields.insert(fields.end(), {"tool_calls", "reasoning_content"});
+        if (role == "tool") fields.insert(fields.end(), {"tool_call_id", "name"});
         for (auto it = m.begin(); it != m.end(); ++it)
-            if (it.key() != "role" && it.key() != "content") fail("unsupported message field: " + it.key());
+            if (std::find(fields.begin(), fields.end(), it.key()) == fields.end()) fail("unsupported message field: " + it.key());
+        // Only an assistant turn may omit content. Text parts are joined with
+        // newlines, as vLLM flattens them for string-content templates.
+        if (!m.contains("content") || m["content"].is_null()) {
+            if (role != "assistant") fail("messages require string or text-part content");
+        } else if (m["content"].is_string()) message.content = m["content"].get<std::string>();
+        else if (m["content"].is_array()) {
+            for (std::size_t k = 0; k < m["content"].size(); ++k) {
+                const auto & part = m["content"][k];
+                if (!part.is_object() || !part.contains("type") || part["type"] != "text" ||
+                    !part.contains("text") || !part["text"].is_string()) fail("content parts must be text");
+                message.content += (k ? "\n" : "") + part["text"].get<std::string>();
+            }
+        } else fail("messages require string or text-part content");
+        if (role == "assistant" && m.contains("reasoning_content") && !m["reasoning_content"].is_null()) {
+            if (!m["reasoning_content"].is_string()) fail("reasoning_content must be a string");
+            message.reasoning = m["reasoning_content"].get<std::string>();
+        }
+        if (role == "assistant" && m.contains("tool_calls") && !m["tool_calls"].is_null()) {
+            if (!m["tool_calls"].is_array()) fail("tool_calls must be an array");
+            for (const auto & c : m["tool_calls"]) {
+                if (!c.is_object() || !c.contains("function") || !c["function"].is_object() ||
+                    !c["function"].contains("name") || !c["function"]["name"].is_string())
+                    fail("tool_calls require a function name");
+                ToolCall call {c["function"]["name"].get<std::string>()};
+                // OpenAI clients send arguments as a JSON string; the template iterates a mapping.
+                if (c["function"].contains("arguments")) {
+                    const auto & a = c["function"]["arguments"];
+                    call.arguments = a.is_string() ? OrderedJson::parse(a.get<std::string>(), nullptr, false) : a;
+                    if (!call.arguments.is_object()) fail("tool call arguments must be a JSON object");
+                }
+                message.calls.push_back(std::move(call));
+            }
+        }
+        messages.push_back(std::move(message));
     }
-    if (messages.back()["role"] != "user") fail("last message must be a user message");
-    // Bailing V3 text template. No hidden, server-owned conversation.
+    if (messages.back().role != "user" && messages.back().role != "tool")
+        fail("last message must be a user or tool message");
+    // Bailing V3 template (chat_template.jinja). No hidden, server-owned conversation.
     const std::string thinking = r.enable_thinking ? "on" : "off";
     r.prompt = "<role>SYSTEM</role>";
     std::size_t start = 0;
-    if (messages.front()["role"] == "system") {
-        auto s = messages.front()["content"].get<std::string>();
+    std::string system;
+    bool system_mode = false;
+    if (messages.front().role == "system") {
+        system = messages.front().content;
         // The explicit API switch owns template control. Normalize conflicting
         // legacy instructions rather than producing two contradictory modes.
         for (const auto old : {std::string("detailed thinking off"), std::string("detailed thinking on")}) {
             std::size_t at = 0;
-            while ((at = s.find(old, at)) != std::string::npos) {
+            while ((at = system.find(old, at)) != std::string::npos) {
                 const auto replacement = "detailed thinking " + thinking;
-                s.replace(at, old.size(), replacement); at += replacement.size();
+                system.replace(at, old.size(), replacement); at += replacement.size();
             }
         }
-        r.prompt += s;
-        if (s.find("detailed thinking off") == std::string::npos && s.find("detailed thinking on") == std::string::npos)
-            r.prompt += "\ndetailed thinking " + thinking;
+        system_mode = system.find("detailed thinking " + thinking) != std::string::npos;
         start = 1;
-    } else r.prompt += "detailed thinking " + thinking;
+    }
+    if (!r.tools.empty()) {
+        if (start) r.prompt += system + "\n";
+        r.prompt += kToolsHeader;
+        for (const auto & tool : r.tools) r.prompt += "\n" + TemplateJson(tool);
+        r.prompt += kToolsFooter;
+        if (!system_mode) r.prompt += "detailed thinking " + thinking;
+    } else if (start) r.prompt += system + (system_mode ? "" : "\ndetailed thinking " + thinking);
+    else r.prompt += "detailed thinking " + thinking;
     r.prompt += "<|role_end|>";
+    auto strip = [](std::string s, bool left, bool right) {
+        if (right) s.erase(s.find_last_not_of('\n') + 1);
+        if (left) s.erase(0, std::min(s.find_first_not_of('\n'), s.size()));
+        return s;
+    };
     for (std::size_t i = start; i < messages.size(); ++i) {
-        const auto role = messages[i]["role"].get<std::string>();
-        auto content = messages[i]["content"].get<std::string>();
-        if (role == "assistant") {
-            const auto close = content.find("</think>");
-            if (close == std::string::npos) r.prompt += "<role>ASSISTANT</role>\n<think></think>";
-            else {
-                auto reasoning = content.substr(0, close);
-                const auto open = reasoning.rfind("<think>");
-                if (open != std::string::npos) reasoning.erase(0, open + 7);
-                const auto first = reasoning.find_first_not_of('\n');
-                reasoning = first == std::string::npos ? "" : reasoning.substr(first, reasoning.find_last_not_of('\n') - first + 1);
-                content = content.substr(content.rfind("</think>") + 8);
-                content.erase(0, std::min(content.find_first_not_of('\n'), content.size()));
-                r.prompt += "<role>ASSISTANT</role>\n<think>" + reasoning + "</think>";
-            }
+        const auto & m = messages[i];
+        if (m.role == "tool") {
+            if (i == 0 || messages[i - 1].role != "tool") r.prompt += "<role>OBSERVATION</role>";
+            r.prompt += "\n<tool_response>\n" + m.content + "\n</tool_response>";
+            if (i + 1 == messages.size() || messages[i + 1].role != "tool") r.prompt += "<|role_end|>";
+            continue;
+        }
+        if (m.role != "assistant") {
+            r.prompt += (m.role == "user" ? "<role>HUMAN</role>" : "<role>SYSTEM</role>") + m.content + "<|role_end|>";
+            continue;
+        }
+        auto content = m.content, reasoning = m.reasoning;
+        if (reasoning.empty() && content.find("</think>") != std::string::npos) {
+            reasoning = strip(content.substr(0, content.find("</think>")), false, true);
+            if (const auto open = reasoning.rfind("<think>"); open != std::string::npos) reasoning.erase(0, open + 7);
+            reasoning = strip(reasoning, true, false);
+            content = strip(content.substr(content.rfind("</think>") + 8), true, false);
         }
-        else r.prompt += role == "user" ? "<role>HUMAN</role>" : "<role>SYSTEM</role>";
-        r.prompt += content + "<|role_end|>";
+        r.prompt += reasoning.empty() ? "<role>ASSISTANT</role>\n<think></think>" + content
+            : "<role>ASSISTANT</role>\n<think>" + strip(reasoning, true, true) + "</think>" + strip(content, true, false);
+        for (std::size_t k = 0; k < m.calls.size(); ++k)
+            r.prompt += (k || !content.empty() ? "\n" : "") + RenderToolCall(m.calls[k]);
+        r.prompt += "<|role_end|>";
     }
     r.prompt += r.enable_thinking ? "<role>ASSISTANT</role>\n<think>" : "<role>ASSISTANT</role>\n<think></think>";
     return r;
@@ -245,4 +358,95 @@ public:
         return TakeUtf8(utf8_, final);
     }
 };
+// Declared string arguments stay raw text; other values parse as JSON and fall
+// back to text, as llama.cpp's ling3 parser types them from the tool schema.
+inline OrderedJson ArgumentValue(const OrderedJson & function, const std::string & key, const std::string & value) {
+    bool text = false, other = false;
+    std::function<void(const OrderedJson &)> scan = [&](const OrderedJson & schema) {
+        if (!schema.is_object()) return;
+        if (schema.contains("type"))
+            for (const auto & type : schema["type"].is_array() ? schema["type"] : OrderedJson::array({schema["type"]}))
+                (type == "string" ? text : other) = true;
+        if (schema.contains("enum") && schema["enum"].is_array())
+            for (const auto & choice : schema["enum"]) (choice.is_string() ? text : other) = true;
+        for (const auto * union_key : {"anyOf", "oneOf"})
+            if (schema.contains(union_key) && schema[union_key].is_array())
+                for (const auto & branch : schema[union_key]) scan(branch);
+    };
+    if (function.contains("parameters") && function["parameters"].is_object() &&
+        function["parameters"].contains("properties") && function["parameters"]["properties"].is_object() &&
+        function["parameters"]["properties"].contains(key)) scan(function["parameters"]["properties"][key]);
+    if (text && !other) return value;
+    auto parsed = OrderedJson::parse(value, nullptr, false);
+    return parsed.is_discarded() ? OrderedJson(value) : parsed;
+}
+// Bailing V3 calls: <tool_call>NAME\n<arg_key>K</arg_key>\n<arg_value>V</arg_value>...\n</tool_call>.
+// Whitespace between the parts is optional and only declared tools are calls.
+// Text after the last call is returned as trailing content, as llama.cpp does.
+struct ToolCalls { bool ok = false; std::vector<ToolCall> calls; std::string trailing; };
+inline ToolCalls ParseToolCalls(std::string_view text, const OrderedJson & tools, bool parallel) {
+    ToolCalls result;
+    auto space = [&] { while (!text.empty() && std::isspace(static_cast<unsigned char>(text.front()))) text.remove_prefix(1); };
+    auto take = [&](std::string_view tag) { if (!text.starts_with(tag)) return false; text.remove_prefix(tag.size()); return true; };
+    auto until = [&](std::string_view tag, std::string & out) {
+        const auto at = text.find(tag);
+        if (at == std::string_view::npos) return false;
+        out = text.substr(0, at); text.remove_prefix(at + tag.size()); return true;
+    };
+    while (space(), take("<tool_call>")) {
+        std::size_t n = 0;
+        while (n < text.size() && !std::isspace(static_cast<unsigned char>(text[n])) && text[n] != '<') ++n;
+        ToolCall call {std::string(text.substr(0, n))};
+        text.remove_prefix(n);
+        const OrderedJson * function = nullptr;
+        for (const auto & tool : tools) if (tool["function"]["name"] == call.name) function = &tool["function"];
+        if (!function) return {};
+        while (space(), !take("</tool_call>")) {
+            std::string key, value;
+            if (!take("<arg_key>") || !until("</arg_key>", key)) return {};
+            space();
+            if (!take("<arg_value>") || !until("</arg_value>", value)) return {};
+            call.arguments[key] = ArgumentValue(*function, key, value);
+        }
+        if (parallel || result.calls.empty()) result.calls.push_back(std::move(call));
+    }
+    if (result.calls.empty()) return {};
+    result.ok = true;
+    result.trailing = text;
+    return result;
+}
+// Holds back generated text from the first <tool_call> so a call never streams
+// as content; with thinking on this also ends the reasoning, as in llama.cpp.
+// The newline the template writes before a call is held too and dropped.
+class ToolCallFilter {
+    std::string pending_, captured_;
+    bool enabled_, newline_ = false;
+public:
+    explicit ToolCallFilter(bool enabled) : enabled_(enabled) {}
+    const std::string & captured() const { return captured_; }
+    // The exact held text, for output that does not parse as calls.
+    std::string Released() const { return (newline_ ? "\n" : "") + captured_; }
+    std::string Push(std::string_view piece, bool final = false) {
+        if (!enabled_) return std::string(piece);
+        if (!captured_.empty()) { captured_ += piece; return {}; }
+        pending_ += piece;
+        constexpr std::string_view tag = "<tool_call>";
+        if (const auto at = pending_.find(tag); at != std::string::npos) {
+            captured_ = pending_.substr(at);
+            pending_.resize(at);
+            newline_ = !pending_.empty() && pending_.back() == '\n';
+            if (newline_) pending_.pop_back();
+            return std::exchange(pending_, {});
+        }
+        std::size_t keep = 0;
+        if (!final) {
+            for (std::size_t k = std::min(tag.size() - 1, pending_.size()); k && !keep; --k)
+                if (pending_.ends_with(tag.substr(0, k))) keep = k;
+            if (keep < pending_.size() && pending_[pending_.size() - keep - 1] == '\n') ++keep;
+        }
+        auto out = pending_.substr(0, pending_.size() - keep);
+        pending_.erase(0, pending_.size() - keep);
+        return out;
+    }
+};
 } // namespace ling3::chat

src/portable_main.cpp

@@ -166,7 +166,7 @@ Json CheckDevice() {
     return report;
 }
 
-struct Result { std::string text, reason = "length"; Json usage, metrics; };
+struct Result { std::string text, reason = "length"; Json usage, metrics; std::vector<ToolCall> tool_calls; };
 class Engine {
     ModelPackage package_;
     std::size_t context_;
@@ -457,6 +457,7 @@ public:
         const bool retain_generated = r.cache_prompt && r.reuse_generated_state;
         std::vector<std::uint32_t> evaluated_tokens = retain_generated ? tokens : std::vector<std::uint32_t>{};
         TextFilter filter(r.stops);
+        ToolCallFilter calls(r.tool_calls);
         std::mt19937 random(r.seed);
         std::vector<bool> seen(logits_.size(), false);
         for (auto token : tokens) if (token < seen.size()) seen[token] = true;
@@ -484,7 +485,7 @@ public:
             if (!generated) { first = last; first_ms = Ms(start, first); }
             ++generated; // includes EOS and stop tokens, like completion usage.
             if (token == package_.header().eos_token) { result.reason = "stop"; break; }
-            if (!output(filter.Push(tokenizer_.Piece(token)))) break;
+            if (!output(calls.Push(filter.Push(tokenizer_.Piece(token))))) break;
             if (filter.stopped) { result.reason = "stop"; break; }
             if (i + 1 < output_budget) {
                 if (!flow_.Wait([&] { return !quitting && connected(); })) { aborted(); break; }
@@ -493,7 +494,18 @@ public:
                 ++evaluated_steps_;
             }
         }
-        if (result.reason != "canceled") output(filter.Push({}, true));
+        if (result.reason != "canceled") output(calls.Push(filter.Push({}, true), true));
+        // Held call text is parsed only once generation is complete; output that
+        // does not parse is released unchanged as content.
+        if (result.reason != "canceled" && !calls.captured().empty()) {
+            auto parsed = ParseToolCalls(calls.captured(), r.tools, r.parallel_tool_calls);
+            if (!parsed.ok) output(calls.Released());
+            else {
+                result.tool_calls = std::move(parsed.calls);
+                output(parsed.trailing);
+                if (result.reason == "stop") result.reason = "tool_calls";
+            }
+        }
         if (result.reason != "canceled" && !alive()) aborted();
         bool continuation_stored = false, continuation_skipped_budget = false;
         double continuation_save_ms = 0;
@@ -536,6 +548,7 @@ public:
             {"queue_ms", 0}, {"cached_tokens", cached_tokens}, {"warmed", true},
             {"cache_status", cache_status}, {"cache_restore_ms", cache_restore_ms},
             {"cache_save_ms", cache_save_ms}, {"prefix_cache_mib", prefix_cache_.bytes() / 1048576.0}};
+        result.metrics["tool_calls"] = result.tool_calls.size();
         result.metrics["context_length"] = context_;
         result.metrics["reuse_generated_state"] = r.reuse_generated_state;
         result.metrics["generated_state_lineage"] = prefix_cache_.generated_lineage;
@@ -743,7 +756,7 @@ void Handle(int fd, Engine & engine, const Json & device) {
         }
         if (http.method != "POST" || http.path != "/v1/chat/completions")
             throw Error(404, "not_found", "endpoint not found");
-        const auto request = Parse(Json::parse(http.body));
+        const auto request = Parse(OrderedJson::parse(http.body));
         const auto id = Id(); const auto created = std::time(nullptr);
         auto chunk = [&](Json delta, Json finish = nullptr) {
             Json out {{"id", id}, {"object", "chat.completion.chunk"}, {"created", created}, {"model", kModel},
@@ -764,14 +777,27 @@ void Handle(int fd, Engine & engine, const Json & device) {
         if (result.reason == "canceled") {
             error(Error(409, "request_canceled", "generation canceled; partial text is not a completed reply")); return;
         }
+        Json tool_calls = Json::array();
+        for (std::size_t i = 0; i < result.tool_calls.size(); ++i)
+            tool_calls.push_back({{"id", "call_" + id.substr(9) + "-" + std::to_string(i)}, {"type", "function"},
+                {"function", {{"name", result.tool_calls[i].name}, {"arguments", result.tool_calls[i].arguments.dump()}}}});
+        Json message {{"role", "assistant"}, {"content", result.text}};
+        if (!tool_calls.empty()) {
+            message["tool_calls"] = tool_calls;
+            if (result.text.empty()) message["content"] = nullptr;
+        }
         if (request.stream) {
+            for (std::size_t i = 0; i < tool_calls.size(); ++i) {
+                tool_calls[i]["index"] = i;
+                chunk({{"tool_calls", Json::array({tool_calls[i]})}});
+            }
             chunk(Json::object(), result.reason);
             Json final {{"id", id}, {"object", "chat.completion.chunk"}, {"created", created}, {"model", kModel},
                 {"choices", Json::array()}, {"mindnano_metrics", result.metrics}};
             if (request.include_usage) final["usage"] = result.usage;
             Send(fd, "data: " + final.dump() + "\n\ndata: [DONE]\n\n");
         } else Response(fd, 200, {{"id", id}, {"object", "chat.completion"}, {"created", created}, {"model", kModel},
-            {"choices", Json::array({{{"index", 0}, {"message", {{"role", "assistant"}, {"content", result.text}}},
+            {"choices", Json::array({{{"index", 0}, {"message", message},
                                      {"finish_reason", result.reason}, {"logprobs", nullptr}}})},
             {"usage", result.usage}, {"mindnano_metrics", result.metrics}});
     } catch (const Error & e) { error(e); }

tests/chat_protocol_test.cpp

@@ -33,7 +33,7 @@ int main() {
         "<role>HUMAN</role>你好<|role_end|><role>ASSISTANT</role>\n<think></think>你好！<|role_end|>"
         "<role>HUMAN</role>继续<|role_end|><role>ASSISTANT</role>\n<think></think>", "template mismatch");
     for (const auto & mutation : std::vector<Json>{
-        {{"tools", Json::array()}}, {{"temperature", -1}}, {{"stream", "true"}},
+        {{"tools", "read_file"}}, {{"tool_choice", "required"}}, {{"temperature", -1}}, {{"stream", "true"}},
         {{"max_tokens", -1}}, {{"max_completion_tokens", 1.5}}, {{"n", 2}},
         {{"model", "other"}}, {{"messages", Json::array()}}, {{"stop", ""}}, {{"cache_prompt", "false"}}}) {
         auto bad = body; bad.update(mutation); bool failed = false;

tests/chat_tools_golden.json

@@ -0,0 +1,464 @@
+[
+ {
+  "name": "no_tools_history",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "system",
+     "content": "请用中文回答"
+    },
+    {
+     "role": "user",
+     "content": "你好"
+    },
+    {
+     "role": "assistant",
+     "content": "你好！"
+    },
+    {
+     "role": "user",
+     "content": "继续"
+    }
+   ],
+   "enable_thinking": false
+  },
+  "prompt": "<role>SYSTEM</role>请用中文回答\ndetailed thinking off<|role_end|><role>HUMAN</role>你好<|role_end|><role>ASSISTANT</role>\n<think></think>你好！<|role_end|><role>HUMAN</role>继续<|role_end|><role>ASSISTANT</role>\n<think></think>"
+ },
+ {
+  "name": "tools_no_system",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Reply with OK."
+    }
+   ],
+   "enable_thinking": false,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "read_file",
+      "description": "Read a file's contents.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role># Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file's contents.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\ndetailed thinking off<|role_end|><role>HUMAN</role>Reply with OK.<|role_end|><role>ASSISTANT</role>\n<think></think>"
+ },
+ {
+  "name": "tools_system",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "system",
+     "content": "You are terse."
+    },
+    {
+     "role": "user",
+     "content": "Use the tools to read /tmp/scratch.txt, then patch it to change 'foo' to 'bar'."
+    }
+   ],
+   "enable_thinking": false,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "read_file",
+      "description": "Read a file's contents.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path"
+       ]
+      }
+     }
+    },
+    {
+     "type": "function",
+     "function": {
+      "name": "patch",
+      "description": "Apply a small text patch to a file.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        },
+        "find": {
+         "type": "string"
+        },
+        "replace": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path",
+        "find",
+        "replace"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role>You are terse.\n# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file's contents.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}\n{\"type\": \"function\", \"function\": {\"name\": \"patch\", \"description\": \"Apply a small text patch to a file.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"find\": {\"type\": \"string\"}, \"replace\": {\"type\": \"string\"}}, \"required\": [\"path\", \"find\", \"replace\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\ndetailed thinking off<|role_end|><role>HUMAN</role>Use the tools to read /tmp/scratch.txt, then patch it to change 'foo' to 'bar'.<|role_end|><role>ASSISTANT</role>\n<think></think>"
+ },
+ {
+  "name": "tools_system_thinking_phrase",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "system",
+     "content": "detailed thinking off\nBe brief."
+    },
+    {
+     "role": "user",
+     "content": "Read /tmp/a."
+    }
+   ],
+   "enable_thinking": false,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "read_file",
+      "description": "Read a file's contents.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role>detailed thinking off\nBe brief.\n# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file's contents.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\n<|role_end|><role>HUMAN</role>Read /tmp/a.<|role_end|><role>ASSISTANT</role>\n<think></think>"
+ },
+ {
+  "name": "tool_loop",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "system",
+     "content": "You are terse."
+    },
+    {
+     "role": "user",
+     "content": "Fix /tmp/a.txt."
+    },
+    {
+     "role": "assistant",
+     "content": null,
+     "tool_calls": [
+      {
+       "id": "call_1",
+       "type": "function",
+       "function": {
+        "name": "read_file",
+        "arguments": "{\"path\": \"/tmp/a.txt\"}"
+       }
+      },
+      {
+       "id": "call_2",
+       "type": "function",
+       "function": {
+        "name": "run",
+        "arguments": "{\"command\": \"ls -l\", \"timeout\": 30, \"env\": {\"A\": \"1\", \"B\": [1, 2.5]}, \"dry\": false}"
+       }
+      }
+     ]
+    },
+    {
+     "role": "tool",
+     "tool_call_id": "call_1",
+     "content": "foo\n"
+    },
+    {
+     "role": "tool",
+     "tool_call_id": "call_2",
+     "content": "total 0"
+    },
+    {
+     "role": "assistant",
+     "content": "Read it.",
+     "tool_calls": [
+      {
+       "id": "call_3",
+       "type": "function",
+       "function": {
+        "name": "patch",
+        "arguments": "{\"path\": \"/tmp/a.txt\", \"find\": \"foo\", \"replace\": \"bar\\n\"}"
+       }
+      }
+     ]
+    },
+    {
+     "role": "tool",
+     "tool_call_id": "call_3",
+     "content": "ok"
+    }
+   ],
+   "enable_thinking": false,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "read_file",
+      "description": "Read a file's contents.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path"
+       ]
+      }
+     }
+    },
+    {
+     "type": "function",
+     "function": {
+      "name": "patch",
+      "description": "Apply a small text patch to a file.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        },
+        "find": {
+         "type": "string"
+        },
+        "replace": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path",
+        "find",
+        "replace"
+       ]
+      }
+     }
+    },
+    {
+     "type": "function",
+     "function": {
+      "name": "run",
+      "description": "运行命令 — 可设超时。",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "command": {
+         "type": "string"
+        },
+        "timeout": {
+         "type": "integer"
+        },
+        "env": {
+         "type": "object"
+        },
+        "dry": {
+         "type": "boolean"
+        }
+       },
+       "required": [
+        "command"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role>You are terse.\n# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file's contents.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}\n{\"type\": \"function\", \"function\": {\"name\": \"patch\", \"description\": \"Apply a small text patch to a file.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"find\": {\"type\": \"string\"}, \"replace\": {\"type\": \"string\"}}, \"required\": [\"path\", \"find\", \"replace\"]}}}\n{\"type\": \"function\", \"function\": {\"name\": \"run\", \"description\": \"运行命令 — 可设超时。\", \"parameters\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}, \"timeout\": {\"type\": \"integer\"}, \"env\": {\"type\": \"object\"}, \"dry\": {\"type\": \"boolean\"}}, \"required\": [\"command\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\ndetailed thinking off<|role_end|><role>HUMAN</role>Fix /tmp/a.txt.<|role_end|><role>ASSISTANT</role>\n<think></think><tool_call>read_file\n<arg_key>path</arg_key>\n<arg_value>/tmp/a.txt</arg_value>\n</tool_call>\n<tool_call>run\n<arg_key>command</arg_key>\n<arg_value>ls -l</arg_value><arg_key>timeout</arg_key>\n<arg_value>30</arg_value><arg_key>env</arg_key>\n<arg_value>{\"A\": \"1\", \"B\": [1, 2.5]}</arg_value><arg_key>dry</arg_key>\n<arg_value>false</arg_value>\n</tool_call><|role_end|><role>OBSERVATION</role>\n<tool_response>\nfoo\n\n</tool_response>\n<tool_response>\ntotal 0\n</tool_response><|role_end|><role>ASSISTANT</role>\n<think></think>Read it.\n<tool_call>patch\n<arg_key>path</arg_key>\n<arg_value>/tmp/a.txt</arg_value><arg_key>find</arg_key>\n<arg_value>foo</arg_value><arg_key>replace</arg_key>\n<arg_value>bar\n</arg_value>\n</tool_call><|role_end|><role>OBSERVATION</role>\n<tool_response>\nok\n</tool_response><|role_end|><role>ASSISTANT</role>\n<think></think>"
+ },
+ {
+  "name": "thinking_tool_loop",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "user",
+     "content": "What is in /tmp/a?"
+    },
+    {
+     "role": "assistant",
+     "content": "",
+     "reasoning_content": "\nI should read it.\n",
+     "tool_calls": [
+      {
+       "id": "call_1",
+       "type": "function",
+       "function": {
+        "name": "read_file",
+        "arguments": "{\"path\": \"/tmp/a\"}"
+       }
+      }
+     ]
+    },
+    {
+     "role": "tool",
+     "tool_call_id": "call_1",
+     "content": "foo"
+    }
+   ],
+   "enable_thinking": true,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "read_file",
+      "description": "Read a file's contents.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role># Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file's contents.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\ndetailed thinking on<|role_end|><role>HUMAN</role>What is in /tmp/a?<|role_end|><role>ASSISTANT</role>\n<think>I should read it.</think><tool_call>read_file\n<arg_key>path</arg_key>\n<arg_value>/tmp/a</arg_value>\n</tool_call><|role_end|><role>OBSERVATION</role>\n<tool_response>\nfoo\n</tool_response><|role_end|><role>ASSISTANT</role>\n<think>"
+ },
+ {
+  "name": "think_in_content",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Hi"
+    },
+    {
+     "role": "assistant",
+     "content": "<think>\nplan\n</think>\n\nHello."
+    },
+    {
+     "role": "user",
+     "content": "读取 /tmp/文件 ✓"
+    }
+   ],
+   "enable_thinking": true,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "read_file",
+      "description": "Read a file's contents.",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "path": {
+         "type": "string"
+        }
+       },
+       "required": [
+        "path"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role># Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file's contents.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\ndetailed thinking on<|role_end|><role>HUMAN</role>Hi<|role_end|><role>ASSISTANT</role>\n<think>plan</think>Hello.<|role_end|><role>HUMAN</role>读取 /tmp/文件 ✓<|role_end|><role>ASSISTANT</role>\n<think>"
+ },
+ {
+  "name": "unicode_call",
+  "request": {
+   "model": "mindnano-ling3-tiny",
+   "messages": [
+    {
+     "role": "user",
+     "content": "打招呼"
+    },
+    {
+     "role": "assistant",
+     "content": null,
+     "tool_calls": [
+      {
+       "id": "call_1",
+       "type": "function",
+       "function": {
+        "name": "run",
+        "arguments": "{\"command\": \"echo 你好\"}"
+       }
+      }
+     ]
+    },
+    {
+     "role": "tool",
+     "tool_call_id": "call_1",
+     "content": "你好"
+    }
+   ],
+   "enable_thinking": false,
+   "tools": [
+    {
+     "type": "function",
+     "function": {
+      "name": "run",
+      "description": "运行命令 — 可设超时。",
+      "parameters": {
+       "type": "object",
+       "properties": {
+        "command": {
+         "type": "string"
+        },
+        "timeout": {
+         "type": "integer"
+        },
+        "env": {
+         "type": "object"
+        },
+        "dry": {
+         "type": "boolean"
+        }
+       },
+       "required": [
+        "command"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "prompt": "<role>SYSTEM</role># Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>\n{\"type\": \"function\", \"function\": {\"name\": \"run\", \"description\": \"运行命令 — 可设超时。\", \"parameters\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}, \"timeout\": {\"type\": \"integer\"}, \"env\": {\"type\": \"object\"}, \"dry\": {\"type\": \"boolean\"}}, \"required\": [\"command\"]}}}\n</tools>\n\nIf none of the functions can be used, point it out. If the given question lacks the parameters required by the function, also point it out.\nIf you need to use a function, for each function call, output the function name and arguments within the following XML format:\n<tool_call>{function-name}\n<arg_key>{arg-key-1}</arg_key>\n<arg_value>{arg-value-1}</arg_value>\n<arg_key>{arg-key-2}</arg_key>\n<arg_value>{arg-value-2}</arg_value>\n...\n</tool_call>\ndetailed thinking off<|role_end|><role>HUMAN</role>打招呼<|role_end|><role>ASSISTANT</role>\n<think></think><tool_call>run\n<arg_key>command</arg_key>\n<arg_value>echo 你好</arg_value>\n</tool_call><|role_end|><role>OBSERVATION</role>\n<tool_response>\n你好\n</tool_response><|role_end|><role>ASSISTANT</role>\n<think></think>"
+ }
+]

tests/chat_tools_test.cpp

@@ -0,0 +1,94 @@
+#include "ling3/chat_protocol.h"
+#include <fstream>
+#include <iostream>
+
+using namespace ling3::chat;
+void Check(bool condition, const std::string & message) {
+    if (!condition) throw std::runtime_error(message);
+}
+int main(int argc, char ** argv) {
+    if (argc != 2) throw std::runtime_error("usage: ling3-chat-tools-test tests/chat_tools_golden.json");
+    // Prompts rendered by transformers from the official chat_template.jinja
+    // (tools/render_chat_tools_golden.py); the C++ renderer must match byte for byte.
+    std::ifstream file(argv[1]);
+    const auto golden = OrderedJson::parse(file);
+    auto find = [&](const std::string & name) -> const OrderedJson & {
+        for (const auto & c : golden) if (c["name"] == name) return c;
+        throw std::runtime_error("missing golden case " + name);
+    };
+    for (const auto & c : golden)
+        Check(Parse(c["request"]).prompt == c["prompt"].get<std::string>(),
+              "template mismatch: " + c["name"].get<std::string>());
+
+    auto body = find("tool_loop")["request"];
+    const auto & tools = body["tools"];
+    const auto prompt = find("tool_loop")["prompt"].get<std::string>();
+    Check(Parse(body).tool_calls && Parse(body).parallel_tool_calls, "tools must enable call parsing");
+    auto none = body; none["tool_choice"] = "none";
+    Check(!Parse(none).tool_calls && Parse(none).prompt == prompt, "tool_choice none still renders tools");
+    auto stored = body; stored["store"] = false;
+    Check(Parse(stored).prompt == prompt, "store flag rejected");
+    auto parts = body;
+    parts["messages"][1]["content"] = OrderedJson::array({{{"type", "text"}, {"text", "Fix /tmp/a.txt."}}});
+    Check(Parse(parts).prompt == prompt, "text-part content");
+    for (const auto & [pointer, value] : std::vector<std::pair<std::string, OrderedJson>>{
+        {"/tools", "read_file"}, {"/tools/0/type", "code"}, {"/tool_choice", "required"},
+        {"/parallel_tool_calls", "yes"}, {"/store", "no"}, {"/messages/2/tool_calls/0/function/arguments", "{oops"},
+        {"/messages/2/tool_calls/0/function/arguments", "[1]"}, {"/messages/3/content", nullptr},
+        {"/messages/3/id", "x"}, {"/messages/1/content", OrderedJson::array({{{"type", "image_url"}}})}}) {
+        auto bad = body; bad[OrderedJson::json_pointer(pointer)] = value; bool failed = false;
+        try { Parse(bad); } catch (const Error &) { failed = true; }
+        Check(failed, "invalid tool request accepted: " + pointer);
+    }
+
+    // Arguments are typed by the declared schema; a parsed call re-renders to
+    // the generated text, so the next turn's prompt keeps the cached prefix.
+    auto calls = ParseToolCalls("<tool_call>run\n<arg_key>command</arg_key>\n<arg_value>123</arg_value>"
+        "<arg_key>timeout</arg_key>\n<arg_value>30</arg_value><arg_key>env</arg_key>\n<arg_value>{\"A\": [1, 2.5]}"
+        "</arg_value><arg_key>dry</arg_key>\n<arg_value>false</arg_value>\n</tool_call>", tools, true);
+    Check(calls.ok && calls.calls.size() == 1 && calls.calls[0].name == "run", "call not parsed");
+    Check(calls.calls[0].arguments.dump() == R"({"command":"123","timeout":30,"env":{"A":[1,2.5]},"dry":false})",
+          "arguments not typed by schema");
+    for (const auto * name : {"tool_loop", "unicode_call", "thinking_tool_loop"})
+        for (const auto & m : find(name)["request"]["messages"]) {
+            if (!m.contains("tool_calls")) continue;
+            std::string generated;
+            for (const auto & c : m["tool_calls"])
+                generated += (generated.empty() ? "" : "\n") + RenderToolCall({c["function"]["name"].get<std::string>(),
+                    OrderedJson::parse(c["function"]["arguments"].get<std::string>())});
+            Check(prompt.find(generated) != std::string::npos || std::string(name) != "tool_loop", "history render");
+            const auto parsed = ParseToolCalls(generated, find(name)["request"]["tools"], true);
+            Check(parsed.ok && parsed.calls.size() == m["tool_calls"].size(), "round trip parse");
+            std::string again;
+            for (const auto & c : parsed.calls) again += (again.empty() ? "" : "\n") + RenderToolCall(c);
+            Check(again == generated, std::string("round trip render: ") + name);
+        }
+    const std::string two = "<tool_call>read_file\n<arg_key>path</arg_key>\n<arg_value>/tmp/a</arg_value>\n</tool_call>\n"
+                            "<tool_call>read_file <arg_key>path</arg_key><arg_value>/tmp/b</arg_value></tool_call>";
+    Check(ParseToolCalls(two, tools, true).calls.size() == 2, "parallel calls");
+    Check(ParseToolCalls(two, tools, false).calls.size() == 1, "parallel_tool_calls=false");
+    Check(ParseToolCalls(two, tools, true).calls[1].arguments["path"] == "/tmp/b", "whitespace-free call");
+    Check(!ParseToolCalls("<tool_call>unknown\n\n</tool_call>", tools, true).ok, "undeclared tool accepted");
+    Check(!ParseToolCalls("<tool_call>read_file\n<arg_key>path</arg_key>\n<arg_value>/tmp", tools, true).ok,
+          "truncated call accepted");
+    Check(ParseToolCalls("<tool_call>read_file\n\n</tool_call>\nDone.", tools, true).trailing == "Done.",
+          "trailing content lost");
+
+    // Streaming: call text and the newline before it are held, never sent as content.
+    ToolCallFilter filter(true);
+    std::string shown;
+    for (const auto * piece : {"Read it.", "\n<tool", "_call>patch\n<arg_key>path</arg_key>",
+                               "\n<arg_value>/tmp/a</arg_value>\n</tool_call>"})
+        shown += filter.Push(piece);
+    shown += filter.Push({}, true);
+    Check(shown == "Read it." && filter.captured().starts_with("<tool_call>patch"), "call text streamed");
+    Check(filter.Released() == "\n" + filter.captured(), "held newline lost");
+    ToolCallFilter plain(true);
+    shown = plain.Push("a <tool");
+    shown += plain.Push("box>\n");
+    shown += plain.Push({}, true);
+    Check(shown == "a <toolbox>\n" && plain.captured().empty(), "false tag prefix withheld");
+    ToolCallFilter off(false);
+    Check(off.Push("<tool_call>x") == "<tool_call>x", "disabled filter held text");
+    std::cout << "chat tools: " << golden.size() << " golden prompts, parsing, round trip, streaming passed\n";
+}

tools/render_chat_tools_golden.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Render OpenAI-style requests with the official Ling-3.0 chat template.
+
+The output is the golden file for tests/chat_tools_test.cpp: each request is
+rendered by transformers' own Jinja renderer, so the C++ prompt builder is
+checked against the template rather than against a reading of it. The
+template is inclusionAI/Ling-3.0-tiny@e3a47d5b986e7141b6efd62597d598ebb392060d
+chat_template.jinja (pass its local path). Tool-call arguments travel as JSON
+strings in the requests, as OpenAI clients send them; the template needs them
+as mappings, as vLLM and llama.cpp convert them.
+"""
+import argparse
+import copy
+import json
+from pathlib import Path
+
+from transformers.utils.chat_template_utils import render_jinja_template
+
+MODEL = "mindnano-ling3-tiny"
+READ = {"type": "function", "function": {"name": "read_file", "description": "Read a file's contents.",
+        "parameters": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}}}
+PATCH = {"type": "function", "function": {"name": "patch", "description": "Apply a small text patch to a file.",
+         "parameters": {"type": "object", "properties": {"path": {"type": "string"}, "find": {"type": "string"},
+                        "replace": {"type": "string"}}, "required": ["path", "find", "replace"]}}}
+RUN = {"type": "function", "function": {"name": "run", "description": "运行命令 — 可设超时。",
+       "parameters": {"type": "object", "properties": {"command": {"type": "string"}, "timeout": {"type": "integer"},
+                      "env": {"type": "object"}, "dry": {"type": "boolean"}}, "required": ["command"]}}}
+
+
+def call(id_, name, **arguments):
+    return {"id": id_, "type": "function", "function": {"name": name, "arguments": json.dumps(arguments, ensure_ascii=False)}}
+
+
+CASES = [
+    ("no_tools_history", False, None, [
+        {"role": "system", "content": "请用中文回答"}, {"role": "user", "content": "你好"},
+        {"role": "assistant", "content": "你好！"}, {"role": "user", "content": "继续"}]),
+    ("tools_no_system", False, [READ], [{"role": "user", "content": "Reply with OK."}]),
+    ("tools_system", False, [READ, PATCH], [
+        {"role": "system", "content": "You are terse."},
+        {"role": "user", "content": "Use the tools to read /tmp/scratch.txt, then patch it to change 'foo' to 'bar'."}]),
+    ("tools_system_thinking_phrase", False, [READ], [
+        {"role": "system", "content": "detailed thinking off\nBe brief."}, {"role": "user", "content": "Read /tmp/a."}]),
+    ("tool_loop", False, [READ, PATCH, RUN], [
+        {"role": "system", "content": "You are terse."}, {"role": "user", "content": "Fix /tmp/a.txt."},
+        {"role": "assistant", "content": None, "tool_calls": [
+            call("call_1", "read_file", path="/tmp/a.txt"),
+            call("call_2", "run", command="ls -l", timeout=30, env={"A": "1", "B": [1, 2.5]}, dry=False)]},
+        {"role": "tool", "tool_call_id": "call_1", "content": "foo\n"},
+        {"role": "tool", "tool_call_id": "call_2", "content": "total 0"},
+        {"role": "assistant", "content": "Read it.", "tool_calls": [
+            call("call_3", "patch", path="/tmp/a.txt", find="foo", replace="bar\n")]},
+        {"role": "tool", "tool_call_id": "call_3", "content": "ok"}]),
+    ("thinking_tool_loop", True, [READ], [
+        {"role": "user", "content": "What is in /tmp/a?"},
+        {"role": "assistant", "content": "", "reasoning_content": "\nI should read it.\n",
+         "tool_calls": [call("call_1", "read_file", path="/tmp/a")]},
+        {"role": "tool", "tool_call_id": "call_1", "content": "foo"}]),
+    ("think_in_content", True, [READ], [
+        {"role": "user", "content": "Hi"},
+        {"role": "assistant", "content": "<think>\nplan\n</think>\n\nHello."},
+        {"role": "user", "content": "读取 /tmp/文件 ✓"}]),
+    ("unicode_call", False, [RUN], [
+        {"role": "user", "content": "打招呼"},
+        {"role": "assistant", "content": None, "tool_calls": [call("call_1", "run", command="echo 你好")]},
+        {"role": "tool", "tool_call_id": "call_1", "content": "你好"}]),
+]
+
+
+def template_messages(messages):
+    messages = copy.deepcopy(messages)
+    for message in messages:
+        for tool_call in message.get("tool_calls", []):
+            tool_call["function"]["arguments"] = json.loads(tool_call["function"]["arguments"])
+    return messages
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--template", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    template = args.template.read_text()
+    golden = []
+    for name, thinking, tools, messages in CASES:
+        rendered, _ = render_jinja_template(conversations=[template_messages(messages)], tools=tools,
+                                            chat_template=template, add_generation_prompt=True,
+                                            enable_thinking=thinking)
+        request = {"model": MODEL, "messages": messages, "enable_thinking": thinking}
+        if tools: request["tools"] = tools
+        golden.append({"name": name, "request": request, "prompt": rendered[0]})
+    args.output.write_text(json.dumps(golden, ensure_ascii=False, indent=1) + "\n")
+
+
+if __name__ == "__main__":
+    main()