Skip to content

feat: Add the core/translate hub with Anthropic Messages and chat completions protocols - #1933

Merged
huang195 merged 9 commits into
rossoctl:mainfrom
huang195:feat/translate-hub-1911-pP1
Nov 17, 2026
Merged

huang195 merged 9 commits into
rossoctl:mainfrom
huang195:feat/translate-hub-1911-pP1

Conversation

@huang195

@huang195 huang195 commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Part of #1911.

This is PR 1 of 3 in a stack. PR 2 adds the forward-proxy layer. PR 3 adds the router config fields.

What changed

  • core/translate/pivot: the pivot type. It holds the request, message, block, tool, event and usage types, and the Protocol interfaces, RequestError and ErrorType.
  • core/translate/anthropic: the Anthropic Messages protocol. DecodeRequest reads an agent request into the pivot. NewReplyEncoder writes pivot events as an Anthropic reply, streamed or not streamed. EncodeError writes an Anthropic error body.
  • core/translate/chat: the chat-completions protocol. EncodeRequest writes the pivot as a chat request and lists the fields that it drops. NewReplyDecoder reads a chat reply, streamed or not streamed, into pivot events. EncodeError writes a chat error body.
  • docs/superpowers/plans/2026-11-17-translation-hub-1911.md: the plan for all 3 PRs.

Nothing calls this package yet. PR 2 connects it to the forward proxy.

How it was tested

  • Unit tests for each protocol. They include the Bob reply shapes, a stream that stops before finish_reason, a piece for a closed tool index, an HTML error page, and tool arguments that are not valid JSON.
  • The plan's full gate passed on the tip d5272467c: go vet, gofmt, go test on the core packages, go mod tidy -diff, and the agentop tests (1111 tests in 8 shards). The fix round da98da43c ran go test -race, go vet and gofmt on core/translate.

Size

  • Counted lines: 2591 (all added, tests included).
  • Exempt lines: 483 (the plan document).

The counted lines are more than the 2000-line limit. The plan estimated 1700 lines. The difference is the test files (864 lines) and the fixes from the task reviews, for example the tool-call id rules.

Review findings that were not fixed

  • [minor] T1: core/translate/pivot/protocol_test.go adds TestRequestError. Task T1 asks only for TestErrorType. The test is small and correct.
  • [minor] T2: core/translate/anthropic/reply.go End() (not streamed) returns a 502 api_error body when the joined tool input is not valid JSON. ReplyEncoder.End() []byte gives no status, so the P2 listener can send this body with the upstream status (for example 200). The chat decoder makes the same check first, so only a decoder that does not check can reach this path. The guard also stops a marshal panic on an invalid json.RawMessage. Possible fixes: write a comment that the decoder is the real check and that the status is not carried, or make the two messages the same ('arguments' in chat, 'input' here), or let P2 (T4 NewReplyReader) get the status from the events.
  • [minor] T2: core/translate/anthropic/reply.go block(): a not-streamed block of a kind other than text, thinking or tool_use (for example redacted_thinking) gives only {"type":"<kind>"}. No producer in this plan makes such a block, because pivot.Event has no field for redacted data. A short comment is enough.
  • [minor] T3: core/translate/chat/reply.go:325 chunkError reads the status only from a numeric code. LiteLLM can write "code":"429" as a string (inferred from ProxyException, not measured). Then the status becomes 500. Only a not-streamed 2xx body with an error sees the wrong status. Fix: remove the quotes before Atoi, and add a "code":"429" case to TestReplyDecoder_ErrorChunk.
  • [minor] T3: core/translate/chat/request.go:245-275: an assistant turn with only unsigned thinking (no text, no tool_use, no signed thinking) is encoded as {"role":"assistant"}, with no content and no tool_calls (a probe confirmed this). OpenAI-style servers can refuse it, and rule 9a sends it again on each later turn. A reply that stops during reasoning (max_tokens) can cause it. No test covers it. Possible fix: send "content":"", or leave out the message.
  • [minor] T3: core/translate/chat/request.go:131-137: the encoder does not put pivot.Tool.Extra keys (for example strict, defer_loading) in dropped, and does not record the unsent thinking.budget_tokens. Decision 11 does not list tools, so the code follows the plan, but this is a gap against rule H4.
  • [minor] T3: the cache_control of a text block inside tool_result.content is not sent. Only the marker on the tool_result block goes on the last part (decision 8). Claude Code puts the marker on the tool_result block, so today's traffic is correct. A marker on an inner block is lost with no dropped entry.
  • [minor] T3: core/translate/chat/reply.go:352-356 (whole): the rule 20 check uses only json.Valid. Valid JSON that is not an object (null, [1], "x") passes and goes to the agent as tool_use input (a probe confirmed this). Anthropic requires an object. Fix: refuse with the same 502 when the trimmed arguments do not start with {.
  • [minor] T3: a block kind that the chat encoder does not know is lost with no correct record. encoder.user and encoder.assistant skip it. A probe with a search_result block in a user turn sent only the other text, and dropped was [content source thinking title], the member names, not the block. A thinking or tool_use block in a user turn is also skipped with no record. Fix: put the block kind in dropped, or refuse with a 400 as rule 14 does for document.
  • [minor] T3: in a stream, a delta after finish_reason and before [DONE] opens a new block after the stop reason is set (a probe gave two text blocks and then stop). No measured server does this. streamDelta could ignore deltas when d.finished is true.
  • [minor] T3: a redacted_thinking entry in thinking_blocks is not sent to the agent. The not-streamed path has a shortcut: comment for this. streamDelta skips it with no comment. Add the same shortcut: comment there.

Review findings deferred in the fix round

  • chat/reply.go streamDelta: in a stream, thinking text comes only from reasoning or reasoning_content (rule 23). A server that sends text only in thinking_blocks gives a signed block with empty text. No known server does this.
  • chat/reply.go streamDelta: the id of the open tool call at a different index opens a second tool_use block with the same id. No known server does this.
  • chat/reply.go Feed: the partial line of a 2xx stream has no size limit. The upstream is a server that the user configured, and a reply that is not streamed also keeps the whole body.
  • chat/request.go user: tool-result images and the other content of the turn go in two user messages in a row (rule 14). Rule 13a also gives user messages in a row, and Bob accepts them.
  • chat/request.go assistant: text blocks are joined with no separator (rule 15).
  • translate/doc.go: the comment names the protocol registry, which PR 2 adds.
  • Size: anthropic and chat each import only pivot, so the PR can split into pivot + anthropic and chat. Not split, because PR 2 is stacked on this branch.

For a human after review

These steps need a live agent, a real server or a person's decision. They are not tasks in this workflow.

  1. Needs T1-T11 (all PRs). Run Claude Code (claude -p, with tools) against a chat-completions server through the router for at least 3 tool-call turns. A local Ollama or llama-server works when its api map has only chat-completions (agentop server add --api chat-completions=/v1/chat/completions …). Put the session id and its turn count in the PR P3 body.
  2. Needs T7. Check that Claude Code's /context still works with the local 404 for count_tokens (rule 6). If it does not, report what Claude Code does. Do not guess a token count.
  3. Needs T3, T8 (and feat: Router server URL path prefix, protocol probe at server add, and IBM Bob defaults #1912 for Bob). Check that Claude Code accepts a __thought__ tool id with + or / and sends it back unchanged. If Claude Code refuses or changes it, report what it does. Do not encode the id without a decision on that report.
  4. Needs T3. On Bob (feat: Router server URL path prefix, protocol probe at server add, and IBM Bob defaults #1912's list), check the rule 11 fields not yet tested there (tool_choice, parallel_tool_calls, stop, temperature, top_p), and that Bob accepts role: tool messages whose content is a list of text parts (decision 8).
  5. Needs P1-P3 opened. Post nothing outside the repository except the PRs themselves; issue comments on feat: Translation hub with Anthropic Messages to and from chat completions, and the api, auth_header and headers server fields #1911 or feat: Inference translation hub, so any agent can run on any inference server (first: Claude Code on IBM Bob) #1910 are a person's call.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

)

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
Name the exact test files. Record the decisions for the hop path and
for record.go. List rules 13a and 14 in the request goldens. Record
that the gate's format and vet steps pass on the base.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
Add core/translate/pivot. It holds the protocol-neutral request, the
reply events and the protocol contract (rules H2, H3 and H4 of rossoctl#1911).
Add the package comment for core/translate.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
Add core/translate/anthropic. It decodes an Anthropic Messages request
to the pivot form, encodes pivot reply events as an Anthropic reply
(streamed or not streamed), and encodes Anthropic error bodies (rules
H2, H3, H4, H6, 13a, 20a, 23 and 24 of rossoctl#1911).

Each field that the pivot has no place for goes to Extra under the
key "anthropic.<field>". A tool with type "custom" is a function tool,
so its Type is empty.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
TestDecodeRequest_Fields now has an image source with an extra member.
The test makes sure that takeSource keeps it as anthropic.source.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
Add core/translate/chat. It encodes a pivot request as a
chat-completions body (rules 9a and 11-19 of rossoctl#1911). It decodes a
chat-completions reply, streamed or not, to pivot events (rules 20-24).

A stream that ends before finish_reason gives an error event, not a
short reply (decision 5). An arguments piece for a closed tool call
gives an error event (decision 6). A non-2xx reply gives one error
event with the upstream message, or the first 512 bytes of the body.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
The stream decoder used only the tool-call index to find the open
tool call. Two whole calls at one index went into one block, so the
second id and name were lost and the input JSON was not valid. Now a
new id on the open index opens a new block (rule 20a).

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
A server that puts every streamed tool call at index 0 closes that
index once for each call. The decoder refused a new id on a closed
index, so the third call got a 502. The decoder now records closed
ids, and refuses a new-id piece only when its id already ended.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>
@huang195
huang195 requested a review from a team as a code owner November 17, 2026 20:33
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: c8a48549-02cc-4789-8d83-6be297e8aa71
Commits

Reviewing files that changed from the base of the PR and between 8695f5f and da98da4.

Files selected for processing: 18

  • core/translate/anthropic/error.go
  • core/translate/anthropic/protocol.go
  • core/translate/anthropic/reply.go
  • core/translate/anthropic/reply_test.go
  • core/translate/anthropic/request.go
  • core/translate/anthropic/request_test.go
  • core/translate/chat/error.go
  • core/translate/chat/protocol.go
  • core/translate/chat/reply.go
  • core/translate/chat/reply_test.go
  • core/translate/chat/request.go
  • core/translate/chat/request_test.go
  • core/translate/doc.go
  • core/translate/pivot/event.go
  • core/translate/pivot/pivot.go
  • core/translate/pivot/protocol.go
  • core/translate/pivot/protocol_test.go
  • docs/superpowers/plans/2026-11-17-translation-hub-1911.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions github-actions Bot added the ready-for-ai-review Request automated AI code review from clawgenti label Nov 17, 2026

@clawgenti clawgenti left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

This is a clean first PR for the translation hub. The pivot types, the Anthropic request decoder and reply encoder, and the chat-completions request encoder and reply decoder match the plan. The tool-call id and index rules from the last two commits hold up. I fed the decoder streams one byte at a time, gave it multi-byte UTF-8, a repeated id on index 0, the same id on every chunk, a delta after finish_reason, and a 429 HTML page, and each case behaved as described. The "Review findings that were not fixed" list is accurate. I agree none of those items blocks this PR, since nothing calls the package yet. I have two suggestions about the reply decoder's input checks, both inline. Neither blocks the merge.

Author: huang195 (MEMBER — maintainer)
Areas reviewed: Go (core/translate/pivot, anthropic, chat), tests, plan doc
Agent/IDE config (.claude/.vscode): none
Commits: 8 commits, all signed-off: yes
CI status: passing (Python Tests (sparc-service) still pending; it does not cover this change). Locally: go test -race ./translate/..., go vet and gofmt -l are clean at d527246.

// replyMessage is a stream delta or a whole message. It does not read
// provider_specific_fields (rule 23).
replyMessage struct {
Content string `json:"content"`

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Content is a string, and both Feed and whole unmarshal into the whole reply struct. So if any member has an unexpected shape, the decoder refuses the whole reply, and it says the reply "is not valid JSON" even when it is valid. I probed this at head:

  • "content":[{"type":"text","text":"hi"}] (some OpenAI-compatible servers send content parts, e.g. Mistral-style thinking/text parts) → 502 a reply that is not valid JSON, in both streamed and not-streamed mode.
  • {"error":"model not loaded"} at 2xx → the same 502, and the server's message is lost.
  • "arguments":{...} as an object instead of a string → the same 502.

Refusing an unknown shape is reasonable. But the message sends whoever debugs it to the wrong cause. Two cheap improvements: (a) use json.Valid first, and when the body is valid JSON, say "the inference server sent a reply in a shape this proxy does not read" (and maybe quote the first bytes, as errorMessage does). (b) Read error as json.RawMessage and accept a bare string as the message. A test for a list content would also fix the current behaviour in place before P2 connects real servers.

return
}
m := r.Choices[0].Message
// Decision 7: check every tool input before any event goes out.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: The not-streamed path is less strict about tool-call ids than the streamed path. The streamed path refuses arguments with no id (before its id) and refuses a repeated id (again after that tool call ended). Here, {"tool_calls":[{"type":"function","function":{"name":"f","arguments":"{}"}}]} (no id) gives a tool_use block with ToolID: "" (I confirmed this in a probe), and two calls with the same id give two blocks with the same id. The agent then sends a tool_result with an empty or ambiguous tool_use_id, and Anthropic clients and Bob can reject that turn. Since this loop already checks every call before any event goes out (decision 7), it could also refuse an empty id or a repeated id with the same 502. That would make both paths follow rule 20a in the same way.

@clawgenti clawgenti left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

The pivot design is genuinely clean — the symmetric optional direction interfaces, the dropped accounting for field-level loss, and the byte-exact golden tests (including bytewise-feed invariance) are stronger than most protocol bridges I've reviewed. 好戏在后头,P2 接上以后这套测试直接就能用 🙂. I read your "Review findings that were not fixed" list and agree with your dispositions; the three findings below are ones your list does not already cover, so nothing here duplicates it. No agent/IDE config files touched, no secrets, no logging of headers/bodies, all commits signed off, CI green.

  1. Unbounded buffer on a 2xx stream with no newline (must consider before P2 wires real upstreams)
  2. No validation of required request fields at the boundary
  3. finish_reason: "stop" collapses stop_sequence into end_turn

The rest are noted inline as suggestions only.

Author: huang195 (MEMBER — maintainer)
Areas reviewed: Go (core/translate: pivot, anthropic, chat), protocol mapping, security
Agent/IDE config (.claude/.vscode): none
Commits: 8 commits, all signed-off: yes
CI status: passing

Verified by: read of the full diff plus the head files core/translate/chat/reply.go and core/translate/anthropic/request.go at d527246; findings cross-checked against the PR body's own "not fixed" list to avoid duplication.

Generated by RepoMan github-pr-review@235a7f7 (https://github.com/rossoctl/agent-skills/blob/235a7f7620139ee3e4ab0872b8439591fe52e8c1/skills/github-pr-review/SKILL.md).

}
return nil
}
d.buf = append(d.buf, p...)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion — 慢工出细活,但这里有个口子 — maxErrorBody (1 MiB) caps only the non-2xx path; on a 2xx stream d.buf = append(d.buf, p...) grows without bound until a \n arrives. A misbehaving or malicious upstream that streams megabytes with no newline grows d.buf unbounded (and each Feed reallocates the partial line via append([]byte(nil), rest...)). Since P2 will point this at real upstreams, a cap belongs here now.

Suggested fix: apply the same 1 MiB room logic to the 2xx partial line and fail with the 502 api_error shape on overflow, mirroring maxErrorBody.

BudgetTokens int `json:"budget_tokens"`
}
err = errors.Join(
take(m, "model", &req.Model),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion — model, messages, and max_tokens are all required by the Anthropic Messages API, but take leaves zero values for absent keys, so {} decodes to an empty pivot request and reaches the chat server as {"model":"","messages":[]} (and max_tokens is dropped entirely via omitempty). The failure then surfaces as an upstream 4xx instead of a clean 400 invalid_request_error at the boundary — the shape the package already produces for malformed blocks. See also temperature/top_p, which pass through with no range check (Anthropic bounds them to 0..1).

Suggested fix: validate the three required fields in decodeRequest and refuse with the existing 400 helper; add a {} body test.

}

// stopReason maps finish_reason by rule 21.
func stopReason(r string) string {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion — 心里有数就好 — "stop" maps to end_turn, so a reply truncated by a stop sequence is indistinguishable from a natural end. stop_sequences is forwarded as chat stop, but the Anthropic client checks stop_reason == "stop_sequence" (to strip the sequence from the tail), and the pivot's StopReason vocabulary can't express it, so the reply encoder can never recover it. If rule 21 in #1911 fixes this later, a one-line comment here saying so would save the next reader the search; otherwise the pivot vocabulary needs a stop_sequence member before P2.

…t streamed

Fixes review: a reply with tool calls and finish_reason "stop" stopped with end_turn. vLLM and OpenAI send "stop" for a forced named tool.
Fixes review: a reply that is not streamed accepted a tool call with no id or a repeated id.
Files:
- core/translate/chat/reply.go
- core/translate/chat/reply_test.go

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>

@clawgenti clawgenti left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

The fix round da98da4 does what it says. A tool call with finish_reason: "stop" now ends with tool_use on both paths (a length cut stays max_tokens). The not-streamed path now refuses a tool call with no id or with a repeated id, so it follows rule 20a the same way the streamed path does. I ran go vet, gofmt -l and go test -race on core/translate/... at head, and all pass (coverage: anthropic 91%, chat 94%, pivot 100%).

I also sent real-world shapes from end to end (chat decoder, then Anthropic encoder). These all worked: OpenAI's full reply (refusal, annotations, logprobs, tool_calls: [], completion_tokens_details), content: null with tool calls, a choices: null usage chunk after finish_reason, finish_reason: null, null cache usage fields, Ollama's single chunk with id, args and finish_reason, a stream with two calls in one chunk and no index, llama-server's {"error":{"code":500,...}} at 200, and a full Claude Code request with a __thought__ id that has +, / and = (the id went through byte for byte). Wrong-typed request members (max_tokens: 1.0, is_error: "true", stop_sequences: "END", a string budget_tokens) each give a clean 400 invalid_request_error that names the field. That is the right result for a request decoder.

The earlier review already covers how strict the reply decoder is about shapes (list content, object arguments, a string error). I don't repeat it here. The comments below are new and none of them blocks the PR.

Author: huang195 (MEMBER — maintainer)
Areas reviewed: Go (core/translate: pivot, anthropic, chat), Docs (plan)
Agent/IDE config (.claude/.vscode): none
Commits: 9 commits, all signed-off: yes
CI status: passing


func imagePart(b pivot.Block) part {
url := b.URL
if b.SourceType == "base64" {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: an image source whose type is not base64 or url goes out as an image part with an empty URL. Probe: {"type":"image","source":{"type":"file","file_id":"f1"}} (Anthropic's Files API source) encodes to {"type":"image_url","image_url":{"url":""}}, and dropped holds only source. The server then answers with an unclear 400 about a bad image URL, or it may drop the image without telling anyone. Rule 14 has a refusal for document. The same 400 invalid_request_error would fit here (for example this inference server cannot read image source type "file"), for any SourceType other than base64 or url.

Message string `json:"message"`
} `json:"error"`
}
if json.Unmarshal(body, &e) == nil && e.Error.Message != "" {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: errorMessage reads only the nested error.message. Older vLLM releases (and some other OpenAI-compatible servers) send a flat error, {"object":"error","message":"The model x does not exist.","type":"NotFoundError","code":404}. For that body the agent gets the whole raw JSON as the message (I probed this with a 404). The status and type are still right, so this only changes how the message reads. A fallback to a top-level message would make it clean.

if anthropicErrorTypes[e.Type] {
t = e.Type
}
d.fail(status, t, e.Message)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: when an {"error":{...}} chunk or body has no message, or an empty one, the agent gets an error with an empty message. errorMessage already falls back to http.StatusText(status) for an empty non-2xx body. The same fallback here (or the error type) would keep the agent's error from being blank.

@huang195
huang195 merged commit 02e489e into rossoctl:main Nov 17, 2026
39 checks passed
@huang195
huang195 deleted the feat/translate-hub-1911-pP1 branch November 17, 2026 21:51
@github-project-automation github-project-automation Bot moved this from New/ToDo to Done in Rossoctl Issue Prioritization Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-ai-review Request automated AI code review from clawgenti

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants