The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(api_server): a budget-exhausted chat turn reports "length", not "cancelled"
Teknium8397dafbcc85
diff --git a/gateway/platforms/api_server_openai_routes.py b/gateway/platforms/api_server_openai_routes.pyindex 9b6c1bfad69..05e2d7b6482 100644--- a/gateway/platforms/api_server_openai_routes.py+++ b/gateway/platforms/api_server_openai_routes.py@@ -68,7 +68,13 @@ def _result_flags(result: Any) -> tuple:bool(result.get("failed")), result.get("error"))-def _finish_reason(completed, is_partial, is_failed, err_msg, agent_error=None) -> str:+def _budget_exhausted(result: Any) -> bool:+ """The turn ran out of its iteration budget; its final text is the agent's own wrap-up."""+ reason = str(result.get("turn_exit_reason") or "") if isinstance(result, dict) else ""+ return reason.startswith(("budget_exhausted", "max_iterations_reached("))+++def _finish_reason(completed, is_partial, is_failed, err_msg, agent_error=None, *, budget_exhausted=False) -> str:"""OpenAI ``finish_reason``: "length" for truncation, "error" for failure, else "stop"."""# OpenAI uses "length" for truncation, "stop" for normal completion, and downstream SDKs accept "error"# / custom codes. See issue #22496.@@ -76,6 +82,10 @@ def _finish_reason(completed, is_partial, is_failed, err_msg, agent_error=None)return "length"if agent_error is not None or is_failed or (not completed and err_msg):return "error"+ # "cancelled" means the user interrupted; a budget-capped turn stopped short of the task instead,+ # and a broker reading "cancelled" discards a usable wrap-up answer.+ if budget_exhausted:+ return "length"return 'cancelled' if not completed else 'stop'@@ -114,10 +124,12 @@ def _response_status(result):return 'completed'-def _hermes_extras(completed, is_partial, is_failed, err_msg, finish_reason: str) -> dict[str, Any]:- return {- "completed": completed, "partial": is_partial, "failed": is_failed, "error": err_msg,- "error_code": "output_truncated" if finish_reason == "length" else "agent_error"}+def _hermes_extras(completed, is_partial, is_failed, err_msg, finish_reason: str, *,+ budget_exhausted: bool = False) -> dict[str, Any]:+ error_code = ("iteration_budget_exhausted" if budget_exhausted and finish_reason == "length"+ else "output_truncated" if finish_reason == "length" else "agent_error")+ return {"completed": completed, "partial": is_partial, "failed": is_failed, "error": err_msg,+ "error_code": error_code}def _transformed_notice() -> str:@@ -969,7 +981,8 @@ class OpenAICompatRoutesMixin:completed, is_partial, is_failed, err_msg = _result_flags(result)if err_msg:err_msg = _redact_api_error_text(err_msg)- finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg)+ budget_exhausted = _budget_exhausted(result)+ finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg, budget_exhausted=budget_exhausted)# Same #13437 identity contract as the SSE path: an explicit-header client is echoed# the stable id it sent; a fingerprint-derived (header-less) turn keeps reporting the# id the agent actually resolved, so headerless clients still learn where the turn went.@@ -1000,7 +1013,8 @@ class OpenAICompatRoutesMixin:response_data["choices"][0]["message"]["reasoning_content"] = reasoning_textif is_partial or is_failed or not completed:response_data["hermes"] = _hermes_extras(- completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason)+ completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason,+ budget_exhausted=budget_exhausted)response_headers["X-Hermes-Completed"] = "false"response_headers["X-Hermes-Partial"] = "true" if is_partial else "false"if err_msg and not presentation_muted:@@ -1149,7 +1163,9 @@ class OpenAICompatRoutesMixin:if agent_error is not None:is_failed = Trueerr_msg = err_msg or str(agent_error)- finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg, agent_error)+ budget_exhausted = _budget_exhausted(result)+ finish_reason = _finish_reason(completed, is_partial, is_failed, err_msg, agent_error,+ budget_exhausted=budget_exhausted)finish_chunk = _chunk({}, finish_reason, usage=_chat_usage_payload(usage))presentation_muted = ((isinstance(result, dict) and result.get("_notification_presentation_suppressed") is True)@@ -1174,7 +1190,8 @@ class OpenAICompatRoutesMixin:"message": err_msg,"type": type(agent_error).__name__ if agent_error else "agent_error"}finish_chunk["hermes"] = _hermes_extras(- completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason)+ completed, is_partial, is_failed, "" if presentation_muted else err_msg, finish_reason,+ budget_exhausted=budget_exhausted)await response.write(_sse_frame(finish_chunk))await response.write(b"data: [DONE]\n\n")except (ConnectionResetError, ConnectionAbortedError, BrokenPipeError, OSError):diff --git a/tests/gateway/test_api_terminal_http.py b/tests/gateway/test_api_terminal_http.pyindex 8500fa5bb35..1fd17665786 100644--- a/tests/gateway/test_api_terminal_http.py+++ b/tests/gateway/test_api_terminal_http.py@@ -1,4 +1,5 @@"""Transport projections never report a non-successful result as completion."""+import jsonfrom unittest.mock import AsyncMockimport pytest@@ -36,6 +37,41 @@ def test_chat_interruption_is_not_stop():from gateway.platforms.api_server_openai_routes import _result_flags, _finish_reasonassert _finish_reason(*_result_flags({'completed': False, 'interrupted': True})) != 'stop'+[email protected]('stream', [False, True])[email protected]('result,finish,code', [+ ({'turn_exit_reason': 'max_iterations_reached(2/2)'}, 'length', 'iteration_budget_exhausted'),+ ({'interrupted': True}, 'cancelled', 'agent_error'),+])+async def test_chat_budget_exhausted_turn_is_length_not_cancelled(stream, result, finish, code):+ """A turn that ran out of iterations delivers its wrap-up as ``length`` with a distinct code; a+ broker reading "cancelled" (reserved for user interrupts) would discard a usable answer."""+ adapter = APIServerAdapter(PlatformConfig(enabled=True))+ adapter._run_agent = AsyncMock(return_value=(+ {'final_response': 'wrap-up', 'completed': False, 'messages': [], **result}, {}))+ app = web.Application()+ app.router.add_post('/v1/chat/completions', adapter._handle_chat_completions)+ try:+ async with TestClient(TestServer(app)) as client:+ response = await client.post('/v1/chat/completions', json={+ 'model': 'hermes', 'stream': stream, 'messages': [{'role': 'user', 'content': 'hi'}]})+ assert response.status == 200+ if stream:+ chunks = [json.loads(line[6:]) for line in (await response.text()).splitlines()+ if line.startswith('data: {')]+ final = chunks[-1]+ content = ''.join(c['choices'][0]['delta'].get('content') or '' for c in chunks)+ else:+ final = await response.json()+ content = final['choices'][0]['message']['content']+ assert content == 'wrap-up'+ assert final['choices'][0]['finish_reason'] == finish+ assert final['hermes']['error_code'] == code+ finally:+ adapter._response_store.close()+ adapter._run_idempotency_store.close()+@pytest.mark.asyncio@pytest.mark.parametrize('flag,status', [('failed', 'failed'), ('interrupted', 'cancelled')])async def test_session_chat_terminal_result_is_not_success(flag, status):diff --git a/website/docs/user-guide/features/api-server.md b/website/docs/user-guide/features/api-server.mdindex 7e890da60a4..2d920eb64d9 100644--- a/website/docs/user-guide/features/api-server.md+++ b/website/docs/user-guide/features/api-server.md@@ -68,6 +68,11 @@ structured through execution; it is not interpreted as a gateway slash command.terminal status and `response.cancelled` / `response.failed` events, including whendiagnostic text is present. Chat Completions reports `finish_reason: "cancelled"`for interrupted turns and `"error"` for failures, not a successful `"stop"`.+- A turn that runs out of its iteration budget (`agent.max_turns`) still answers with the+ agent's wrap-up of what it found. Chat Completions delivers that text with+ `finish_reason: "length"` and `hermes.error_code: "iteration_budget_exhausted"`;+ Responses reports `status: "incomplete"`. Treat the content as a usable answer to a task+ that stopped short, not as a cancellation.- Session-chat replies include `status`; their streams report matching terminal runevents. An assistant finalization frame is not itself proof of successful execution.