fix(api): fail-closed whitespace-only mode on tools passthrough

[cursor]

Summary

Successor to #613 at 37f1224. Unique commit e3bffe0.

#613 hoisted mode/trace checks before proxy_completion, but _validate_chat_passthrough_orchestration_controls skipped whitespace-only mode / orchestration / orchestration_mode (not candidate.strip() → continue). The orchestration path uses body.get("orchestration") or body.get("orchestration_mode") or body.get("mode") or "auto" and then _validate_mode. A space-only string is truthy there, so the same body is 400 invalid_mode without tools and a billed chat.completion with tools.

• Reuse that or chain so whitespace-only mode is invalid_mode on passthrough.
• Live HTTP cases: tools + mode: " " → 400; tools + mode=route → 200/choices; orchestration_mode=explode; response_format + mode=conduct.
• Docs next-action now names mode=route alongside auto / omit.

Buyer next action: omit mode or send auto/route; do not send whitespace-only mode. Omit mode=conduct and include_orchestration_trace=true on tool-calling requests. Keep omitting seed, stop, n>1, and logprobs.

Do not merge #601 or #613 in parallel. Prefer this head. Merge only after Full unit + Semgrep are green and an independent non-author review lands.

Test plan

• python3 tests/test_passthrough_mode_trace_http_honesty.py
• python3 tests/test_chat_orchestration_mode_http_honesty.py
• python3 tests/test_chat_include_orchestration_trace_http_honesty.py
• python3 tests/test_include_orchestration_trace_null_noop_http_honesty.py
• python3 tests/test_paper_contracts.py test_self_check.py test_conventions.py test_api_contract.py test_product_planning_contract.py
• CI Full unit + Semgrep

Docs

• CHANGELOG, README, docs/rest_api_design.md, docs/architecture.md record the whitespace or-chain and mode=route no-op.

References

• Nielsen, S., Cetin, E., Schwendeman, P., Sun, Q., Xu, J., & Tang, Y. (2025). Learning to orchestrate agents in natural language with the Conductor. arXiv. https://doi.org/10.48550/arXiv.2512.04388
• Xu, J., Sun, Q., Schwendeman, P., Nielsen, S., Cetin, E., & Tang, Y. (2025). Trinity: An evolved LLM coordinator. arXiv. https://doi.org/10.48550/arXiv.2512.04695
• OpenAI. (2024). Create chat completion. OpenAI API reference. https://platform.openai.com/docs/api-reference/chat/create

  

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[cursor]

Mixed aliases bill a completion on this head

Whitespace-only mode is correctly invalid_mode when it is the first truthy alias. Collapsing orchestration / orchestration_mode / mode into one or chain reintroduces a billed omit.

Live HTTP on this head (e3bffe0):

{"model": "mock-planner", "messages": [{"role": "user", "content": "look up invoice 4419"}], "tools": [{"type": "function", "function": {"name": "lookup_balance", "parameters": {"type": "object"}}}], "orchestration": "route", "mode": "conduct"}

returns 200 with choices — a billed chat.completion. The same hide applies to orchestration=route plus mode: " ".

The orchestration path may use or to pick a single mode. Passthrough still has to reject every alias that asked for a workflow this path cannot run (Nielsen et al., 2025; Xu et al., 2025).

The defect is contextual_orchestrator/server.py _validate_chat_passthrough_orchestration_controls: body.get("orchestration") or body.get("orchestration_mode") or body.get("mode"). orchestration=route is truthy, so mode=conduct never reaches _validate_mode.

Buyer next action: omit mode or send auto/route. Do not send spaces, mode=conduct, or mixed orchestration=route plus mode=conduct.

Do not merge this head. Repair is per-key checks (JSON null/"" omit; whitespace and conduct fail closed on each key) plus live HTTP for the mixed body. Successor unique is #647. If the SSE tip is the landing stack, prefer #640 — it already keeps per-key checks. Do not merge #601 / #613 / #629 in parallel.

View PR

  

_{Sent by Cursor Automation: Fix Issues}