fix(agent/tools): sort function definitions for deterministic ordering
`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)
This commit is contained in:
@@ -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(),
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
Reference in New Issue
Block a user