From 29bec4204a3fe743efdf7c4cc8effd11ba43e45b Mon Sep 17 00:00:00 2001 From: young1lin <2550110827@qq.com> Date: Mon, 25 May 2026 11:37:12 +0800 Subject: [PATCH] fix(agent/tools): sort function definitions for deterministic ordering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `ToolRegistry.GetFunctionDefinitions` and `ListTools` previously ranged over the internal map directly. Go map iteration is intentionally randomized, so the resulting `tools` array reshuffled on every request. That reshuffling silently breaks provider-side prompt caches that key on a byte-level prefix match — most visibly Qwen explicit caching, which requires the messages (system + tools + history) to be byte-identical up to the `cache_control` marker. With random ordering the serialized tools block changes every call, so the cache prefix never matches and the hit rate stays at 0%. Sort by tool name in both functions. Output is now byte-stable across calls and `cache_control: ephemeral` can actually take effect. Tests in registry_test.go cover: - Deterministic ordering across 50 iterations - JSON byte-stability across 20 iterations (the real motivation) - Field projection (Name / Description / Parameters) - Empty registry returns `[]` not `null` - ListTools sorting - First-wins duplicate registration policy (GHSA-67q9-58vj-32qx) --- internal/agent/tools/registry.go | 24 +++- internal/agent/tools/registry_test.go | 156 ++++++++++++++++++++++++++ 2 files changed, 176 insertions(+), 4 deletions(-) create mode 100644 internal/agent/tools/registry_test.go diff --git a/internal/agent/tools/registry.go b/internal/agent/tools/registry.go index 892c3002..3ef3d03a 100644 --- a/internal/agent/tools/registry.go +++ b/internal/agent/tools/registry.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "fmt" + "sort" "github.com/Tencent/WeKnora/internal/common" "github.com/Tencent/WeKnora/internal/logger" @@ -62,19 +63,34 @@ func (r *ToolRegistry) GetTool(name string) (types.Tool, error) { return tool, nil } -// ListTools returns all registered tool names +// ListTools returns all registered tool names sorted alphabetically. +// Sorting keeps the order stable across calls — Go map iteration is +// intentionally randomized. func (r *ToolRegistry) ListTools() []string { names := make([]string, 0, len(r.tools)) for name := range r.tools { names = append(names, name) } + sort.Strings(names) return names } -// GetFunctionDefinitions returns function definitions for all registered tools +// GetFunctionDefinitions returns function definitions for all registered tools. +// The slice is sorted by tool name so the serialized payload sent to the LLM +// is byte-identical across requests. Providers that key prompt caching on a +// byte-level prefix match (e.g. Qwen explicit caching) require this — map +// iteration order would otherwise reshuffle the tools block and break cache +// hits. func (r *ToolRegistry) GetFunctionDefinitions() []types.FunctionDefinition { - definitions := make([]types.FunctionDefinition, 0) - for _, tool := range r.tools { + names := make([]string, 0, len(r.tools)) + for name := range r.tools { + names = append(names, name) + } + sort.Strings(names) + + definitions := make([]types.FunctionDefinition, 0, len(names)) + for _, name := range names { + tool := r.tools[name] definitions = append(definitions, types.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), diff --git a/internal/agent/tools/registry_test.go b/internal/agent/tools/registry_test.go new file mode 100644 index 00000000..25cf84b6 --- /dev/null +++ b/internal/agent/tools/registry_test.go @@ -0,0 +1,156 @@ +package tools + +import ( + "context" + "encoding/json" + "fmt" + "sort" + "testing" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// mockTool is a minimal types.Tool implementation for registry tests. +type mockTool struct { + name string + description string + parameters json.RawMessage +} + +func (m *mockTool) Name() string { return m.name } +func (m *mockTool) Description() string { return m.description } +func (m *mockTool) Parameters() json.RawMessage { return m.parameters } +func (m *mockTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) { + return &types.ToolResult{Success: true}, nil +} + +// registerMany registers a batch of mock tools with the given names. +func registerMany(t *testing.T, r *ToolRegistry, names []string) { + t.Helper() + for _, n := range names { + r.RegisterTool(&mockTool{ + name: n, + description: "desc-" + n, + parameters: json.RawMessage(fmt.Sprintf(`{"type":"object","title":"%s"}`, n)), + }) + } +} + +// TestGetFunctionDefinitions_DeterministicOrder pins the core invariant: the +// output is sorted by tool name and identical across repeated calls. Go's map +// iteration is intentionally randomized, so without an explicit sort the slice +// can reshuffle on every call — which silently breaks byte-level prompt prefix +// caching at providers like Qwen. +func TestGetFunctionDefinitions_DeterministicOrder(t *testing.T) { + // Insertion order is deliberately non-alphabetical to make any accidental + // "insertion order" implementation fail this test. + names := []string{"zeta", "alpha", "kappa", "beta", "gamma", "delta", "epsilon", "omega"} + + r := NewToolRegistry() + registerMany(t, r, names) + + expected := append([]string(nil), names...) + sort.Strings(expected) + + // Many iterations because map randomization may happen to match the sorted + // order on a single call. + const iterations = 50 + var prev []string + for i := 0; i < iterations; i++ { + defs := r.GetFunctionDefinitions() + require.Len(t, defs, len(names)) + + got := make([]string, len(defs)) + for j, d := range defs { + got[j] = d.Name + } + + assert.Equal(t, expected, got, "iteration %d: definitions must be sorted by name", i) + if prev != nil { + assert.Equal(t, prev, got, "iteration %d: definitions must match the previous call", i) + } + prev = got + } +} + +// TestGetFunctionDefinitions_JSONByteStable is the real motivation for the +// sort: two consecutive calls must produce byte-identical JSON so the prompt +// prefix sent to the LLM stays stable and explicit caches can hit. +func TestGetFunctionDefinitions_JSONByteStable(t *testing.T) { + r := NewToolRegistry() + registerMany(t, r, []string{"search", "fetch", "code_run", "answer", "wiki", "kb_query"}) + + first, err := json.Marshal(r.GetFunctionDefinitions()) + require.NoError(t, err) + + for i := 0; i < 20; i++ { + next, err := json.Marshal(r.GetFunctionDefinitions()) + require.NoError(t, err) + assert.Equal(t, string(first), string(next), + "iteration %d: JSON-serialized tool definitions must be byte-stable", i) + } +} + +// TestGetFunctionDefinitions_PreservesFields verifies the projection from +// types.Tool to types.FunctionDefinition keeps every field intact. +func TestGetFunctionDefinitions_PreservesFields(t *testing.T) { + r := NewToolRegistry() + r.RegisterTool(&mockTool{ + name: "search", + description: "Search the knowledge base", + parameters: json.RawMessage(`{"type":"object","properties":{"q":{"type":"string"}},"required":["q"]}`), + }) + + defs := r.GetFunctionDefinitions() + require.Len(t, defs, 1) + assert.Equal(t, "search", defs[0].Name) + assert.Equal(t, "Search the knowledge base", defs[0].Description) + assert.JSONEq(t, + `{"type":"object","properties":{"q":{"type":"string"}},"required":["q"]}`, + string(defs[0].Parameters), + ) +} + +// TestGetFunctionDefinitions_Empty returns an empty (non-nil) slice for an +// empty registry. Callers may json.Marshal the result and expect `[]`, not +// `null`. +func TestGetFunctionDefinitions_Empty(t *testing.T) { + r := NewToolRegistry() + + defs := r.GetFunctionDefinitions() + assert.NotNil(t, defs) + assert.Empty(t, defs) + + encoded, err := json.Marshal(defs) + require.NoError(t, err) + assert.Equal(t, "[]", string(encoded)) +} + +// TestListTools_Sorted mirrors the determinism guarantee for ListTools. +func TestListTools_Sorted(t *testing.T) { + names := []string{"zeta", "alpha", "kappa", "beta"} + r := NewToolRegistry() + registerMany(t, r, names) + + expected := append([]string(nil), names...) + sort.Strings(expected) + + for i := 0; i < 20; i++ { + assert.Equal(t, expected, r.ListTools(), "iteration %d: ListTools must be sorted", i) + } +} + +// TestRegisterTool_DuplicateRejected guards the first-wins policy that +// prevents tool execution hijacking via name collision (GHSA-67q9-58vj-32qx). +// A re-registration must not overwrite the original tool. +func TestRegisterTool_DuplicateRejected(t *testing.T) { + r := NewToolRegistry() + r.RegisterTool(&mockTool{name: "search", description: "original"}) + r.RegisterTool(&mockTool{name: "search", description: "impostor"}) + + defs := r.GetFunctionDefinitions() + require.Len(t, defs, 1) + assert.Equal(t, "original", defs[0].Description, "first registration must win") +}