Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ Injection is protocol-aware: Chat system and developer messages are folded into

On every shaped free-model request the gateway replaces each named client tool with an opaque wire name, `clint_` plus the first 12 hex characters of the client name's SHA-256 (collisions get a `_2`, `_3`, … suffix), and appends the complete official tool set for the lane: the 1.x definitions (`bash`, `edit`, `glob`, `grep`, `read`, `skill`, `task`, `todowrite`, `webfetch`, `websearch`, `write`) on `/zen`, and the 13-tool 2.x set on `/inference` and `/zen/go`. The digest is not cosmetic: the free tier refuses a shaped body that still carries another client's vocabulary — a Claude Code request that declares both `ReportFindings` and `ScheduleWakeup` is answered with `FreeUsageLimitError`, and removing either name lifts the refusal — so no client tool name reaches the wire. Requests without a `tools` array, with an empty one, or with a legacy `functions` array get the same official set; `tool_choice`, legacy `function_call`, and the tool-call history are rewritten to match. Responses built-in tools and Anthropic server tools are left untouched.

Responses are restored to the names the client declared, for streaming and non-streaming replies, including a Chat tool name split across chunks. If the upstream calls an official tool the client never declared, that name passes through unchanged: the gateway does not replay or hide official tool calls.
Responses are restored to client-declared names in streaming and non-streaming replies, including Chat tool names split across chunks. An official name is mapped when the client declared an equivalent tool; otherwise it remains unchanged in the response. In request history, unknown tool calls and official calls without a declared equivalent are removed with their paired results, and a named `tool_choice` targeting one of those dropped calls is removed too.

### Free model availability

Expand Down
4 changes: 2 additions & 2 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,9 +262,9 @@ System One 将自由文本状态与类型化问题配对,并返回类型化答

### 工具整形

每个经过整形的免费模型请求中,网关会把客户端声明的每个具名工具改名为 `clint_<name>`——`A-Za-z0-9_-` 之外的字符替换为 `_`,名称最长 64 字节,冲突时追加 `_2`、`_3` 等后缀——并追加该通道的完整官方工具集:`/zen` 使用 1.x 定义(`bash`、`edit`、`glob`、`grep`、`read`、`skill`、`task`、`todowrite`、`webfetch`、`websearch`、`write`),`/inference` 与 `/zen/go` 使用 13 个工具的 2.x 定义。没有 `tools`、`tools` 为空数组或使用旧版 `functions` 数组的请求同样会补全官方工具集;`tool_choice`、旧版 `function_call` 和工具调用历史会同步改写。Responses 内置工具和 Anthropic 服务端工具保持不变。
每个经过整形的免费模型请求中,网关会把客户端声明的每个具名工具改名为不透明的线上名称 `clint_` 加上客户端名称 SHA-256 的前 12 个十六进制字符(冲突时追加 `_2`、`_3` 等后缀),并追加该通道的完整官方工具集:`/zen` 使用 1.x 定义(`bash`、`edit`、`glob`、`grep`、`read`、`skill`、`task`、`todowrite`、`webfetch`、`websearch`、`write`),`/inference` 与 `/zen/go` 使用 13 个工具的 2.x 定义。没有 `tools`、`tools` 为空数组或使用旧版 `functions` 数组的请求同样会补全官方工具集;`tool_choice`、旧版 `function_call` 和工具调用历史会同步改写。Responses 内置工具和 Anthropic 服务端工具保持不变。

响应会恢复为客户端声明的名称,流式与非流式均适用,包括被拆分到多个 Chat 分块中的工具名。如果上游调用了客户端从未声明的官方工具,该名称会原样透传:网关不会重放或隐藏官方工具调用。
响应(包括流式与非流式,以及拆分到多个 Chat 分块中的工具名)会恢复为客户端声明的名称。只有在客户端声明了等价工具时,官方工具名才会映射到客户端名称;否则响应中的名称保持原样。整形请求历史时,未知工具调用以及没有客户端等价工具的官方调用会连同配对的结果一起移除;若具名 `tool_choice` 指向被移除的工具,也会一并移除。

### 免费模型可用性

Expand Down
285 changes: 285 additions & 0 deletions internal/gateway/toolshape.go
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,40 @@ func officialToolNames(v1 bool) []string {
return v2OfficialToolOrder
}

// OfficialToolCandidates returns client tool names equivalent to an official name.
func OfficialToolCandidates(officialName string) []string {
switch strings.ToLower(officialName) {
case "bash", "shell":
return []string{"Bash"}
case "edit":
return []string{"Edit"}
case "glob":
return []string{"Glob"}
case "grep":
return []string{"Grep"}
case "question":
return []string{"AskUserQuestion"}
case "read":
return []string{"Read"}
case "skill":
return []string{"Skill"}
case "subagent", "task":
return []string{"Agent", "Task", "Subagent"}
case "todowrite":
return []string{"TodoWrite"}
case "webfetch":
return []string{"WebFetch"}
case "websearch":
return []string{"WebSearch"}
case "write":
return []string{"Write"}
case "patch":
return []string{"Patch"}
default:
return nil
}
}

// officialToolDefinition returns the captured definition for an official name.
func officialToolDefinition(name string, v1 bool) (opencodeToolDefinition, bool) {
loadOfficialTools()
Expand Down Expand Up @@ -191,8 +225,26 @@ func renameAndCompleteTools(payload map[string]any, protocol wire.Protocol, v1 b
items = list
}
}
declaredNames := make([]string, 0, len(items))
for _, item := range items {
entry, ok := item.(map[string]any)
if !ok {
continue
}
if name, ok := renamableToolName(protocol, entry); ok {
declaredNames = append(declaredNames, name)
}
}
if protocol == wire.Chat || protocol == wire.Responses {
if legacy, ok := payload["functions"].([]any); ok {
for _, rawEntry := range legacy {
entry, ok := rawEntry.(map[string]any)
if ok {
if name := jsonutil.StringAt(entry, "name"); name != "" {
declaredNames = append(declaredNames, name)
}
}
}
items = append(items, convertLegacyFunctions(legacy, protocol, renames, used)...)
delete(payload, "functions")
}
Expand All @@ -216,10 +268,243 @@ func renameAndCompleteTools(payload map[string]any, protocol wire.Protocol, v1 b
}
shaped = append(shaped, officialToolset(protocol, v1)...)
payload["tools"] = shaped
officialNames := officialToolNames(v1)
bindOfficialToolAliases(renames, declaredNames, officialNames)
declared := make(map[string]string, len(declaredNames))
for _, name := range declaredNames {
if wireName, ok := renames.Wire(name); ok {
declared[name] = wireName
}
}
sanitizeToolHistory(payload, protocol, declared, renames, officialToolNameSet(v1))
rewriteToolReferences(payload, protocol, renames)
return renames, true
}

func bindOfficialToolAliases(renames *wire.ToolRenames, declaredNames, officialNames []string) {
for _, official := range officialNames {
candidates := OfficialToolCandidates(official)
for _, declared := range declaredNames {
if _, exists := renames.Wire(declared); !exists {
continue
}
for _, candidate := range candidates {
if match, _ := renames.Resolve(candidate); match == declared {
renames.BindOfficial(official, declared)
break
}
}
if _, exists := renames.Official(official); exists {
break
}
}
}
}

func officialToolNameSet(v1 bool) map[string]bool {
set := make(map[string]bool)
for _, name := range officialToolNames(v1) {
set[name] = true
}
return set
}

func sanitizeToolHistory(payload map[string]any, protocol wire.Protocol, declared map[string]string, renames *wire.ToolRenames, laneOfficial map[string]bool) {
dropped := map[string]bool{}
switch protocol {
case wire.Anthropic:
messages := jsonutil.SliceAt(payload, "messages")
for _, rawMessage := range messages {
message, _ := rawMessage.(map[string]any)
for _, rawBlock := range jsonutil.SliceAt(message, "content") {
block, _ := rawBlock.(map[string]any)
if jsonutil.StringAt(block, "type") != "tool_use" {
continue
}
name := jsonutil.StringAt(block, "name")
if wireName, ok := historyToolWireName(name, declared, renames, laneOfficial); ok {
block["name"] = wireName
} else if id := jsonutil.StringAt(block, "id"); id != "" {
dropped[id] = true
}
}
}
keptMessages := make([]any, 0, len(messages))
for _, rawMessage := range messages {
message, _ := rawMessage.(map[string]any)
content, ok := message["content"].([]any)
if !ok {
keptMessages = append(keptMessages, rawMessage)
continue
}
keptContent := make([]any, 0, len(content))
for _, rawBlock := range content {
block, _ := rawBlock.(map[string]any)
switch jsonutil.StringAt(block, "type") {
case "tool_use":
if _, ok := historyToolWireName(jsonutil.StringAt(block, "name"), declared, renames, laneOfficial); !ok {
continue
}
case "tool_result":
if dropped[jsonutil.StringAt(block, "tool_use_id")] {
continue
}
}
keptContent = append(keptContent, rawBlock)
}
if len(keptContent) == 0 {
continue
}
message["content"] = keptContent
keptMessages = append(keptMessages, rawMessage)
}
payload["messages"] = keptMessages
case wire.Chat:
messages := jsonutil.SliceAt(payload, "messages")
dropEmptyMessages := make(map[int]bool)
for index, rawMessage := range messages {
message, _ := rawMessage.(map[string]any)
calls, ok := message["tool_calls"].([]any)
if !ok {
continue
}
keptCalls := make([]any, 0, len(calls))
for _, rawCall := range calls {
call, _ := rawCall.(map[string]any)
function, _ := call["function"].(map[string]any)
name := jsonutil.StringAt(function, "name")
if wireName, ok := historyToolWireName(name, declared, renames, laneOfficial); ok {
function["name"] = wireName
keptCalls = append(keptCalls, rawCall)
} else if id := jsonutil.StringAt(call, "id"); id != "" {
dropped[id] = true
}
}
if len(keptCalls) == 0 {
delete(message, "tool_calls")
dropEmptyMessages[index] = len(calls) > 0
} else {
message["tool_calls"] = keptCalls
}
}
keptMessages := make([]any, 0, len(messages))
for index, rawMessage := range messages {
message, _ := rawMessage.(map[string]any)
if jsonutil.StringAt(message, "role") == "tool" && dropped[jsonutil.StringAt(message, "tool_call_id")] {
continue
}
if dropEmptyMessages[index] && !chatMessageHasContent(message) {
continue
}
keptMessages = append(keptMessages, rawMessage)
}
payload["messages"] = keptMessages
case wire.Responses:
items := jsonutil.SliceAt(payload, "input")
for _, rawItem := range items {
item, _ := rawItem.(map[string]any)
switch jsonutil.StringAt(item, "type") {
case "function_call", "custom_tool_call":
name := jsonutil.StringAt(item, "name")
if wireName, ok := historyToolWireName(name, declared, renames, laneOfficial); ok {
item["name"] = wireName
} else if id := jsonutil.FirstString(jsonutil.StringAt(item, "call_id"), jsonutil.StringAt(item, "id")); id != "" {
dropped[id] = true
}
}
}
keptItems := make([]any, 0, len(items))
for _, rawItem := range items {
item, _ := rawItem.(map[string]any)
if jsonutil.StringAt(item, "type") == "function_call_output" && dropped[jsonutil.StringAt(item, "call_id")] {
continue
}
if kind := jsonutil.StringAt(item, "type"); kind == "function_call" || kind == "custom_tool_call" {
if _, ok := historyToolWireName(jsonutil.StringAt(item, "name"), declared, renames, laneOfficial); !ok {
continue
}
}
keptItems = append(keptItems, rawItem)
}
payload["input"] = keptItems
}
sanitizeToolChoice(payload, protocol, declared, renames, laneOfficial)
}

func historyToolWireName(name string, declared map[string]string, renames *wire.ToolRenames, laneOfficial map[string]bool) (string, bool) {
if wireName, ok := declared[name]; ok {
return wireName, true
}
if _, ok := renames.Client(name); ok {
return name, true
}
if laneOfficial[name] {
client, ok := renames.Official(name)
if !ok {
client, _ = renames.Resolve(name)
}
if wireName, ok := declared[client]; ok {
return wireName, true
}
return renames.Wire(client)
}
client, _ := renames.Resolve(name)
if wireName, ok := declared[client]; ok {
return wireName, true
}
return "", false
}

func chatMessageHasContent(message map[string]any) bool {
for _, key := range []string{"content", "reasoning_content", "reasoning"} {
switch value := message[key].(type) {
case string:
if value != "" {
return true
}
case []any:
if len(value) > 0 {
return true
}
case map[string]any:
if len(value) > 0 {
return true
}
case nil:
default:
return true
}
}
return false
}

func sanitizeToolChoice(payload map[string]any, protocol wire.Protocol, declared map[string]string, renames *wire.ToolRenames, laneOfficial map[string]bool) {
choice, ok := payload["tool_choice"].(map[string]any)
if !ok {
return
}
kind := jsonutil.StringAt(choice, "type")
if kind != "tool" && kind != "function" && kind != "custom" {
return
}
target := choice
if protocol == wire.Chat {
if function, ok := choice["function"].(map[string]any); ok {
target = function
}
}
name := jsonutil.StringAt(target, "name")
if name == "" {
return
}
wireName, ok := historyToolWireName(name, declared, renames, laneOfficial)
if !ok {
delete(payload, "tool_choice")
return
}
target["name"] = wireName
}

// renamableToolName returns the client tool name of one definition. Responses
// built-in tools (web search and similar) have no client name and are left
// untouched.
Expand Down
Loading
Loading