refactor(config): centralize agent ModelSettings via resolve_model_settings()

Adding an agent-facing LLM knob previously meant touching every agent builder
to read yet another get_*() (extra_headers, timeout_extra_args,
parallel_tool_calls, …) — and it was easy to forget one: build_lint_agent
never set parallel_tool_calls, so query and lint silently disagreed on it.

Add config.resolve_model_settings(), the single place that assembles all
agents-SDK ModelSettings kwargs from the process-wide runtime stashes. Both
build_query_agent and build_lint_agent now do
`ModelSettings(**resolve_model_settings())`, so a new knob is wired in one
place and every agent stays in sync. It assembles on read from the existing
getters, preserving "set_extra_headers(...) reaches the agent" (used by the
compiler and by tests) rather than snapshotting into a separate stash.

Note: build_lint_agent now also honors parallel_tool_calls (it didn't before),
making lint consistent with query/chat — including needing `null` on Bedrock.

Author: KylinMountain

openkb/agent/linter.py

@@ -8,7 +8,7 @@
 from agents.model_settings import ModelSettings
 
 from openkb.agent.tools import list_wiki_files, read_wiki_file
-from openkb.config import get_extra_headers, get_timeout_extra_args
+from openkb.config import resolve_model_settings
 from openkb.schema import get_agents_md
 
 MAX_TURNS = 50
@@ -82,10 +82,7 @@ def read_file(path: str) -> str:
         instructions=instructions,
         tools=[list_files, read_file],
         model=f"litellm/{model}",
-        model_settings=ModelSettings(
-            extra_headers=get_extra_headers() or None,
-            extra_args=get_timeout_extra_args(),
-        ),
+        model_settings=ModelSettings(**resolve_model_settings()),
     )
 
 

openkb/agent/query.py

@@ -12,7 +12,7 @@
     read_wiki_image,
     write_kb_file,
 )
-from openkb.config import get_extra_headers, get_parallel_tool_calls, get_timeout_extra_args
+from openkb.config import resolve_model_settings
 from openkb.schema import get_agents_md
 
 MAX_TURNS = 50
@@ -95,11 +95,7 @@ def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
         instructions=instructions,
         tools=[read_file, get_page_content, get_image],
         model=f"litellm/{model}",
-        model_settings=ModelSettings(
-            parallel_tool_calls=get_parallel_tool_calls(),
-            extra_headers=get_extra_headers() or None,
-            extra_args=get_timeout_extra_args(),
-        ),
+        model_settings=ModelSettings(**resolve_model_settings()),
     )
 
 

openkb/config.py

@@ -300,6 +300,23 @@ def get_parallel_tool_calls() -> bool | None:
     return _runtime_parallel_tool_calls
 
 
+def resolve_model_settings() -> dict[str, Any]:
+    """Assemble the agents-SDK ``ModelSettings`` kwargs from the process-wide LLM
+    runtime settings (populated by ``cli._setup_llm_key``).
+
+    This is the single place that maps runtime LLM config onto agent model
+    settings: every agent builder does ``ModelSettings(**resolve_model_settings())``
+    rather than enumerating the individual getters, so a new agent-facing knob
+    is wired in here once and can't be silently forgotten by one builder.
+    ``None`` values are what the agents SDK treats as "unset / provider default".
+    """
+    return {
+        "extra_headers": get_extra_headers() or None,
+        "extra_args": get_timeout_extra_args(),
+        "parallel_tool_calls": get_parallel_tool_calls(),
+    }
+
+
 def load_config(config_path: Path) -> dict[str, Any]:
     """Load YAML config from config_path, merged with DEFAULT_CONFIG.
 

tests/test_config.py

@@ -8,6 +8,7 @@
     load_config,
     resolve_extra_headers,
     resolve_litellm_settings,
+    resolve_model_settings,
     resolve_parallel_tool_calls,
     resolve_timeout,
     save_config,
@@ -17,6 +18,30 @@
 )
 
 
+def test_resolve_model_settings_assembles_from_runtime_stashes():
+    # One place that assembles every agents-SDK ModelSettings kwarg from the
+    # process-wide runtime stashes, so agent builders don't each enumerate them.
+    set_extra_headers({"X-A": "1"})
+    set_timeout(1200.0)
+    set_parallel_tool_calls(False)
+    assert resolve_model_settings() == {
+        "extra_headers": {"X-A": "1"},
+        "extra_args": {"timeout": 1200.0},
+        "parallel_tool_calls": False,
+    }
+
+
+def test_resolve_model_settings_empty_is_all_omitted():
+    set_extra_headers({})
+    set_timeout(None)
+    set_parallel_tool_calls(None)
+    assert resolve_model_settings() == {
+        "extra_headers": None,
+        "extra_args": None,
+        "parallel_tool_calls": None,
+    }
+
+
 def test_parallel_tool_calls_defaults_to_false():
     # Default preserves the historical behavior: force sequential tool calls.
     assert DEFAULT_CONFIG["parallel_tool_calls"] is False