Support POST /v1/responses: OpenAI's newest models cannot use function tools without it

[mostlydev]

Running cllama:v0.7.7; source read at clawdapus@v0.27.0-15-gf42af36 (cllama/).

Summary

cllama routes only POST /v1/chat/completions and POST /v1/messages. OpenAI has moved function-tool support for its newest models to /v1/responses, so a cllama-mediated agent cannot use managed tools with those models at all. This is not a niche gap — it tracks OpenAI's direction, so it widens with each release.

Evidence

Measured live against the OpenAI API, one trivial function tool, reasoning_effort: high, POST /v1/chat/completions:

Model	Result
gpt-5.6-terra	400 — Function tools with reasoning_effort are not supported for gpt-5.6-terra in /v1/chat/completions. To use function tools, use /v1/responses or set reasoning_effort to 'none'.
gpt-5.6-luna	400 — same
gpt-5-pro	404 — This model is only supported in v1/responses and not in v1/chat/completions.
gpt-5	200 OK
gpt-5-mini	200 OK

Two details worth noting, because both are easy to get wrong:

• It is not about the effort level. gpt-5.6-terra + tools returns 400 with reasoning_effort set to high, set to medium, and omitted entirely. These models always reason, so "tools + reasoning" is unconditional on chat/completions. Only the explicit reasoning_effort: "none" escape returns 200.
• The affected set is the newest tier. gpt-5/gpt-5-mini still work the old way; the 5.6 family and gpt-5-pro do not. So the practical effect today is that cllama confines agents to the previous model generation whenever they need tools.

Current state in source

• cllama/cmd/cllama/main.go:140-141 — only POST /v1/chat/completions and POST /v1/messages are registered
• cllama/internal/proxy/handler.go:1402 — if !strings.HasPrefix(path, "/v1/chat/completions")

A request to /v1/responses therefore 404s at the mux.

Why this is a second pipeline, not a route addition

Flagging this so the work is scoped honestly rather than discovered midway. cllama's value is that all agent traffic crosses one audited path, and the following are all built around the chat/completions request/response shape:

• Managed tool mediation (internal/proxy/toolmediation.go) — the bounded multi-round loop, duplicate-call detection, and tool_trace assembly. Responses uses a different tool-call and tool-result representation.
• Session history normalization — the JSONL turn record, including reported_cost_usd.
• Budget enforcement — token-usage extraction for spend accounting; the usage block differs.
• Audit events — request, response, error, tool_call, intervention.
• Streaming — synthetic SSE re-streaming when the runner asked for a stream; Responses has its own event taxonomy.
• Candidate/failover dispatch (dispatchCandidates) — declared model candidates and cooldown behaviour.

Each guarantee has to be re-established and re-proven for the new shape. A partial implementation that routes but does not audit would be worse than the current 404, because it would silently stop governing.

Suggested direction

1. Register POST /v1/responses and resolve provider/candidates through the existing declared-model path, so failover and cooldown behave identically.
2. Normalize Responses turns into the same session-history record shape, so history, cost, and claw audit stay uniform across request shapes.
3. Port managed tool mediation to the Responses tool-call representation, preserving round limits, timeouts, duplicate policy, and tool_trace.
4. Until it lands, consider a clear startup or per-request diagnostic when a declared model is known to be responses-only. Today the failure surfaces downstream as 502 no usable declared provider key after retries / exhausted declared model candidates, which points at credentials and sent us looking at API keys, provider pools, and egress before we found the real cause in the upstream 400.

Point 4 is cheap and independently valuable even before the main work.

[mostlydev]

Follow-up with live evidence that materially narrows the design I proposed above. I framed this as registering an inbound POST /v1/responses route — a second pipeline. I now think that is the wrong shape, and the smaller fix is strictly better.

The target is proven

gpt-5.6-terra, reasoning.effort: high, one function tool, against POST /v1/responses:

status: completed | model: gpt-5.6-terra
  output type=reasoning
  output type=function_call name=ping
usage keys: input_tokens, input_tokens_details, output_tokens, output_tokens_details, total_tokens

Reasoning and tool calling together, on the exact model that 400s on chat/completions.

Better shape: an outbound provider adapter, not an inbound route

cllama can keep accepting POST /v1/chat/completions from agents and translate to /v1/responses at the provider boundary, only for models that require it.

Why this is meaningfully smaller and safer than what I first suggested:

• No second inbound pipeline. Every runner (Hermes, OpenClaw, Pico, …) keeps speaking one shape. No runner changes at all.
• Governance surfaces do not move. Audit events, tool_trace, session-history normalization, and budget accounting all observe the agent-facing shape, which is unchanged — so none of them need re-proving. That was my main objection to the route-addition design, and this avoids it entirely.
• Tool mediation keeps its structure. toolmediation.go's bounded round loop, duplicate policy, and timeouts are untouched; only the upstream encoding at the dispatch boundary changes.
• Failover still works. Declared model candidates and cooldown logic stay in dispatchCandidates; the adapter sits under it.

The translation surface is mechanical

Request:

chat/completions	responses
messages	input
tools[].function.{name,description,parameters}	tools[].{name,description,parameters} (flattened, type: "function")
reasoning_effort: "high"	reasoning: {effort: "high"}
max_completion_tokens	max_output_tokens

Response:

responses	chat/completions
output[] entries of type function_call	choices[0].message.tool_calls[]
output[] entries of type message	choices[0].message.content
output[] entries of type reasoning	dropped, or retained as metadata
usage.input_tokens / output_tokens / total_tokens	usage.prompt_tokens / completion_tokens / total_tokens

The usage mapping matters: budget enforcement already reads the chat field names, so translating usage keeps spend accounting correct with no changes to the budget code.

Selection

Route to the adapter per declared model rather than by probing. A static list plus an opt-in override is enough; alternatively, treat an upstream 400 carrying To use function tools, use /v1/responses as a one-time signal to retry through the adapter and remember the result.

Streaming is the one genuinely non-mechanical part — the Responses event taxonomy differs from chat SSE deltas. A first cut could translate non-streaming only and let the existing synthetic SSE re-streaming path present it to runners that asked for a stream.

The diagnostic suggestion in the original post stands and is still worth doing independently: today this surfaces as 502 no usable declared provider key after retries, which points squarely at credentials.

[mostlydev]

Reviewed issue-31-responses-adapter (through fix(proxy): surface failed Responses objects on the direct dispatch path). The design matches what was proposed and the governance-critical parts are right. Notes from a consumer currently blocked on this workload: gpt-5.6-terra + reasoning_effort: high + 11 managed tools.

Confirmed correct:

• Outbound adapter rather than an inbound /v1/responses route, so agents keep one shape and no runner changes are needed. responsesAPIRequired(providerName, upstreamModel) selects per model.
• Usage mapping is the load-bearing detail and it is right — prompt_tokens ← input_tokens, completion_tokens ← output_tokens, plus *_tokens_details. Budget/spend accounting reads the chat names, so this keeps enforcement working with no budget-code changes.
• Tool translation both ways: tool_calls → function_call items, role:"tool" → function_call_output, and reasoning_effort → reasoning.effort.
• Audit survives: LogIntervention(..., "responses_api_adapter"), plus responses_api_adapter_retry and a responses_adapter_error fallback reason. That is what makes this a real lift rather than routing-without-governing.
• Streaming handled by buffering (adapterAwareAttemptContext) instead of hand-rolling the Responses event taxonomy. Right call for a first cut.
• Retrying an unknown responses-only model through the adapter once, rather than requiring the static list to be exhaustive.

store: false deserves specific credit. The Responses API persists turns provider-side by default where chat/completions does not, so routing through the adapter without it would have quietly started retaining agent traffic at the provider. That is a data-retention change, not a plumbing detail — for us it lands directly against a retention posture our operator attested this week. It was not in my original write-up and it should have been.

Two things worth verifying before merge, both about parity rather than correctness:

1. Session history must record adapter turns identically. Audit interventions are clearly emitted; what I could not confirm from the diff is that a turn dispatched through the adapter lands in history.jsonl with the same shape and a populated reported_cost_usd. If claw audit and history diverge by request shape, the uniformity that makes them trustworthy is gone.
2. tool_trace through the mediated loop. toolmediation.go gained ~76 lines; worth an explicit assertion that a multi-round managed-tool turn through the adapter produces the same tool_trace entries as the chat path.

Both are exactly what a downstream lift check would exercise, so they are cheap to assert now and annoying to discover later.

A downstream integration check can exercise the full path: managed tool manifest injection from tools.json, reasoning at high, and a model that 400s on chat/completions today.

[mostlydev]

Both pre-merge asks are now locked as regressions on the branch (618ec46):

1. Session-history parity — TestAdapterTurnRecordsChatShapedSessionHistoryWithCost asserts an adapter-dispatched turn lands in history.jsonl with path: /v1/chat/completions, a chat-shaped request_effective (messages, never input), a chat.completion response payload, usage tokens populated from the translated reply, and a populated reported_cost_usd (verified to ~$0.0075 for a priced model routed through the adapter via CLLAMA_RESPONSES_API_MODELS).

   One caveat you'll hit in practice: DefaultPricing() has no rates for the adapter's built-in models (gpt-5.6 family, gpt-5-pro), so their history entries will carry a null reported_cost_usd until rates are added. That's a pricing-table gap, not a shape divergence — the same turn on chat/completions would also be unpriced. If you can supply the rates, it's a two-line table addition.

2. tool_trace parity — TestAdapterMediatedToolTraceMatchesChatPath runs the identical two-round managed turn (tool call → executed receipt → final text) once on the chat path and once through the adapter, then compares the recorded tool_trace structurally with volatile timings normalized. The traces are byte-identical apart from wall_time_ms — same rounds, names, arguments, ok/status envelopes, and per-round usage. A vacuity guard asserts the trace actually contains the tool call.

For downstream integration verification, the branch head is 618ec46. A case with 11 managed tools, reasoning_effort: high, and a responses-only model exercises the mediated multi-round path end to end, which is exactly the surface these tests approximate with fixtures.

[mostlydev]

Fixed by #32, merged as 31d9715. gpt-5.6-* and gpt-5-pro now dispatch through the outbound Responses adapter with managed tool mediation, failover, audit, budget, and session-history parity — all verified by the regression suite discussed above. Reasoning continuity across mediated rounds is tracked separately in #33; pricing rates for these models in #36. Live-test offer from the reporter still welcome against master.