From aac2da6413057343052440babdbdb79f3aec2b27 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 13 Nov 2026 23:53:14 +0000 Subject: [PATCH 1/3] feat(settings): persist a per-conversation budget in ConversationSettings ConversationSettings gains max_budget_per_run (USD, > 0, default None) in the general section next to max_iterations, and create_request() forwards it to StartConversationRequest.max_budget_per_run. Clients that render the conversation-settings schema (Agent Canvas) can now offer the budget, so conversations started from a UI are no longer unbounded by default. Co-authored-by: openhands --- openhands-sdk/openhands/sdk/settings/model.py | 16 +++++++++ tests/agent_server/test_settings_router.py | 1 + tests/sdk/test_settings.py | 33 ++++++++++++++++++- 3 files changed, 49 insertions(+), 1 deletion(-) diff --git a/openhands-sdk/openhands/sdk/settings/model.py b/openhands-sdk/openhands/sdk/settings/model.py index 46e2cd01f31..4f513700c02 100644 --- a/openhands-sdk/openhands/sdk/settings/model.py +++ b/openhands-sdk/openhands/sdk/settings/model.py @@ -1238,6 +1238,21 @@ class ConversationSettings(BaseModel): ).model_dump() }, ) + max_budget_per_run: float | None = Field( + default=None, + gt=0, + description=( + "Maximum accumulated LLM cost, in USD, for one conversation. The " + "run stops once the conversation's cost reaches it. Leave empty " + "for no limit." + ), + json_schema_extra={ + SETTINGS_METADATA_KEY: SettingsFieldMetadata( + label="Max budget per conversation (USD)", + prominence=SettingProminence.MAJOR, + ).model_dump() + }, + ) confirmation_mode: bool = Field( default=False, description="Require user confirmation before executing risky actions.", @@ -1475,6 +1490,7 @@ def _start_request_kwargs(self, **kwargs: Any) -> dict[str, Any]: payload.setdefault("confirmation_policy", self._build_confirmation_policy()) payload.setdefault("security_analyzer", self._build_security_analyzer()) payload.setdefault("max_iterations", self.max_iterations) + payload.setdefault("max_budget_per_run", self.max_budget_per_run) return payload def create_request( diff --git a/tests/agent_server/test_settings_router.py b/tests/agent_server/test_settings_router.py index 1f3d40d6dee..034d3f901b0 100644 --- a/tests/agent_server/test_settings_router.py +++ b/tests/agent_server/test_settings_router.py @@ -259,6 +259,7 @@ def test_get_settings_migrates_legacy_openhands_settings_and_resaves_current( assert body["conversation_settings"] == { "schema_version": CONVERSATION_SETTINGS_SCHEMA_VERSION, "max_iterations": 42, + "max_budget_per_run": None, "confirmation_mode": True, "security_analyzer": "llm", "default_runtime": "local", diff --git a/tests/sdk/test_settings.py b/tests/sdk/test_settings.py index 81a0c003c1e..350bf6be7b7 100644 --- a/tests/sdk/test_settings.py +++ b/tests/sdk/test_settings.py @@ -207,9 +207,11 @@ def test_conversation_settings_export_schema_groups_sections() -> None: sections = {s.key: s for s in schema.sections} general_fields = {f.key: f for f in sections["general"].fields} - assert set(general_fields) == {"max_iterations"} + assert set(general_fields) == {"max_iterations", "max_budget_per_run"} assert general_fields["max_iterations"].default == 500 assert general_fields["max_iterations"].prominence is SettingProminence.MAJOR + assert general_fields["max_budget_per_run"].default is None + assert general_fields["max_budget_per_run"].prominence is SettingProminence.MAJOR verification_fields = {f.key: f for f in sections["verification"].fields} assert set(verification_fields) == { @@ -339,6 +341,7 @@ def test_conversation_settings_validates_observability_metadata() -> None: def test_conversation_settings_model_dump_roundtrip() -> None: settings = ConversationSettings( max_iterations=42, + max_budget_per_run=2.5, confirmation_mode=True, security_analyzer="none", ) @@ -383,6 +386,34 @@ def test_conversation_settings_create_request() -> None: assert overridden_request.security_analyzer is None +def test_conversation_settings_create_request_forwards_budget() -> None: + workspace = LocalWorkspace(working_dir="/tmp") + agent = OpenHandsAgentSettings(llm=LLM(model="test-model")).create_agent() + + unset = ConversationSettings().create_request( + StartConversationRequest, agent=agent, workspace=workspace + ) + budgeted = ConversationSettings(max_budget_per_run=2.5).create_request( + StartConversationRequest, agent=agent, workspace=workspace + ) + overridden = ConversationSettings(max_budget_per_run=2.5).create_request( + StartConversationRequest, + agent=agent, + workspace=workspace, + max_budget_per_run=None, + ) + + assert unset.max_budget_per_run is None + assert budgeted.max_budget_per_run == 2.5 + assert overridden.max_budget_per_run is None + + +@pytest.mark.parametrize("budget", [0, -1]) +def test_conversation_settings_rejects_non_positive_budget(budget: float) -> None: + with pytest.raises(ValidationError): + ConversationSettings(max_budget_per_run=budget) + + def test_conversation_settings_create_request_with_acp_agent() -> None: settings = ConversationSettings( max_iterations=77, From 3fd41713ef40895e5608269ebd554695cc727216 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 15 Nov 2026 03:58:31 +0000 Subject: [PATCH 2/3] feat(settings): label the budget as the default for new conversations The value is copied into each new conversation's start request; it does not edit an existing conversation's budget (PATCH /api/conversations/{id} does that). Rename the label to "Default budget per conversation (USD)" and say so in the description. Co-authored-by: openhands --- openhands-sdk/openhands/sdk/settings/model.py | 9 +++++---- tests/sdk/test_settings.py | 7 +++++++ 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/openhands-sdk/openhands/sdk/settings/model.py b/openhands-sdk/openhands/sdk/settings/model.py index 4f513700c02..300251a6e23 100644 --- a/openhands-sdk/openhands/sdk/settings/model.py +++ b/openhands-sdk/openhands/sdk/settings/model.py @@ -1242,13 +1242,14 @@ class ConversationSettings(BaseModel): default=None, gt=0, description=( - "Maximum accumulated LLM cost, in USD, for one conversation. The " - "run stops once the conversation's cost reaches it. Leave empty " - "for no limit." + "Default maximum accumulated LLM cost, in USD, for new " + "conversations. Each new conversation stops once its cost reaches " + "it. Changing it does not affect existing conversations. Leave " + "empty for no limit." ), json_schema_extra={ SETTINGS_METADATA_KEY: SettingsFieldMetadata( - label="Max budget per conversation (USD)", + label="Default budget per conversation (USD)", prominence=SettingProminence.MAJOR, ).model_dump() }, diff --git a/tests/sdk/test_settings.py b/tests/sdk/test_settings.py index 350bf6be7b7..7b2b0dc3e39 100644 --- a/tests/sdk/test_settings.py +++ b/tests/sdk/test_settings.py @@ -212,6 +212,13 @@ def test_conversation_settings_export_schema_groups_sections() -> None: assert general_fields["max_iterations"].prominence is SettingProminence.MAJOR assert general_fields["max_budget_per_run"].default is None assert general_fields["max_budget_per_run"].prominence is SettingProminence.MAJOR + assert ( + general_fields["max_budget_per_run"].label + == "Default budget per conversation (USD)" + ) + assert "new conversations" in ( + general_fields["max_budget_per_run"].description or "" + ) verification_fields = {f.key: f for f in sections["verification"].fields} assert set(verification_fields) == { From 7b5af7381afd21bc42e72e07cfae1b1e12649900 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 15 Nov 2026 05:07:35 +0000 Subject: [PATCH 3/3] test(settings): an explicit budget kwarg beats a different settings budget Co-authored-by: openhands --- tests/sdk/test_settings.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tests/sdk/test_settings.py b/tests/sdk/test_settings.py index 7b2b0dc3e39..2c454610ab6 100644 --- a/tests/sdk/test_settings.py +++ b/tests/sdk/test_settings.py @@ -409,10 +409,17 @@ def test_conversation_settings_create_request_forwards_budget() -> None: workspace=workspace, max_budget_per_run=None, ) + raised = ConversationSettings(max_budget_per_run=2.5).create_request( + StartConversationRequest, + agent=agent, + workspace=workspace, + max_budget_per_run=5.0, + ) assert unset.max_budget_per_run is None assert budgeted.max_budget_per_run == 2.5 assert overridden.max_budget_per_run is None + assert raised.max_budget_per_run == 5.0 @pytest.mark.parametrize("budget", [0, -1])