Add multi-LLM /model switching, settings precedence, round-time persistence

- config: named 'models' profiles in config.json (load_models_config)
- session: switch_model() applies profile settings over llm config,
  preserves conversation history, applies timeout to the HTTP pool
- TUI: /model lists profiles with numbered selection and switches by
  name; /restore latest alias; persisted round timestamps restored
  from session metadata
- docs: README models section and /model command

Author: beacoder

README.md

@@ -81,16 +81,32 @@ LLM settings live in a JSON config file — no environment variables required:
 ```json
 {
   "llm": {
-    "base_url": "https://api.deepseek.com/v1",
+    "base_url": "https://api.openai.com/v1",
     "api_key": "sk-...",
-    "model": "deepseek-chat",
-    "reasoning_effort": "medium",
+    "model": "gpt-5-mini",
+    "reasoning_effort": null,
     "stream": true
   },
+  "models": {
+    "_comment": "Named LLM profiles for /model switching. Each entry is a partial set of LLM settings; unset keys inherit the main llm.",
+    "deepseek": {
+      "base_url": "https://api.deepseek.com/v1",
+      "model": "deepseek-chat",
+      "reasoning_effort": "medium"
+    },
+    "qwen": {
+      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "model": "qwen3.5-coder"
+    },
+    "kimi": {
+      "base_url": "https://api.moonshot.cn/v1",
+      "model": "kimi-k2.7"
+    }
+  },
   "subagent_llm": {
     "base_url": null,
     "api_key": null,
-    "model": "deepseek-chat",
+    "model": null,
     "temperature": null,
     "max_tokens": null,
     "timeout": null,
@@ -120,6 +136,7 @@ LLM settings live in a JSON config file — no environment variables required:
 - `reasoning_effort` is passed to the API as-is (omitted when unset) — whatever your provider accepts ("low"/"medium"/"high").
 - Other optional keys: `backend`, `temperature`, `max_tokens`, `timeout`, `stream` (`true` by default; `run --no-stream` overrides on the command line).
 - `subagent_llm` configures the LLM for Agent-tool requests: every key is optional and unset keys inherit the main `llm`, so a cheaper/smaller model (or a different provider) can serve delegated work.
+- **Named model profiles** (`models` section) enable runtime switching via `/model`: each profile is a partial LLM settings dict; unset keys inherit the main `llm`. Use `/model` in the TUI to switch between providers/models without restarting.
 - `paths.context_path` / `paths.skill_path` override context/skill discovery — defaults are `<project>/contexts` or `~/.emacs.d/contexts` (skills: `<project>/skills` or `~/.emacs.d/skills`).
 - `mcp.servers` configures MCP servers (requires the `[mcp]` extra). Each server is `{transport, command, args, env, url, headers, parallel, timeout, enabled}` — `stdio` needs `command`/`args` (optionally `env` naming environment variables to pass through, e.g. `["GITHUB_TOKEN"]`); `streamable-http`/`sse` need `url` (optionally `headers`). Its tools appear as `mcp__<server>__<tool>`.
 - Precedence: code defaults < config file < `OPENAI_*` env vars (env still wins if set, but nothing is required). Sub-agent settings honor `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`, `_BACKEND`).
@@ -145,6 +162,7 @@ python-agent-harness run [project-dir]   # interactive TUI agent
 | `/sessions` | list saved sessions |
 | `/restore [path\|title\|--latest]` | restore a session (title substring match) |
 | `/clear` | start a fresh conversation |
+| `/model [name]` | switch LLM model profile (no arg: list available; with arg: switch to that profile) |
 | `/exit` | quit |
 
 Custom commands from `prompts/commands/*.md` are registered as slash commands too (TUI-only — no CLI subcommand is registered for them). Tool availability differs per command: `/init` and `/review` may use all tools except `PlanExit` (hidden for the run, including for spawned sub-agents); custom commands may use everything; `compact`/`summary` run with no tools (a one-shot `chat_sync` call, like session-title generation).

python_agent_harness/agent_session.py

@@ -90,6 +90,9 @@ def __init__(
         skill_path: str | None = None,
         mcp: MCPConfig | None = None,
         mcp_manager: MCPManager | None = None,
+        model_profiles: dict[str, dict] | None = None,
+        llm_settings: dict | None = None,
+        config_path: str | None = None,
     ) -> None:
         self.project_dir = project_dir
         self.client = client
@@ -170,6 +173,12 @@ def __init__(
         self._save_error: str | None = None
         self.last_messages: list = []
         self.cancel_event = threading.Event()
+        # Named LLM profiles for runtime switching via /model command
+        self.model_profiles: dict[str, dict] = model_profiles or {}
+        # Resolved main llm settings (base for /model switching): a
+        # model profile's unset keys inherit these values, so switching
+        # between profiles never drifts settings from earlier switches.
+        self.llm_settings: dict = dict(llm_settings) if llm_settings else {}
         # Monotonic cancel identity: cancel() bumps this counter, so a
         # worker from a cancelled run can tell it was cancelled even
         # after the next run clears the shared event.
@@ -608,6 +617,76 @@ def cancel(self) -> None:
                 with contextlib.suppress(Exception):  # best effort
                     c.abort()
 
+    # ------------------------------------------------------------------
+    # model switching
+    # ------------------------------------------------------------------
+    def switch_model(self, name: str) -> tuple[bool, str]:
+        """Switch to a named LLM profile.
+
+        Model-specific settings take precedence over the main ``llm``
+        config; keys the profile leaves unset inherit the main ``llm``
+        settings as resolved at session start (so switching between
+        profiles never drifts values from earlier switches).  The
+        client and session are updated in place.  Returns
+        (success, message).
+        """
+        if not self.model_profiles or name not in self.model_profiles:
+            available = (
+                ", ".join(sorted(self.model_profiles.keys()))
+                if self.model_profiles
+                else "(none configured)"
+            )
+            return False, f"unknown model: {name} (available: {available})"
+        profile = self.model_profiles[name]
+        # Effective settings: main llm config (resolved at session
+        # start) overlaid with the profile's own settings.  Profile
+        # keys that are set (not None) win; unset keys inherit the llm
+        # config, which itself falls back to the current session values
+        # for callers that don't pass llm_settings.
+        merged = dict(self.llm_settings)
+        current = {
+            "base_url": self.client.base_url,
+            "api_key": self.client.api_key,
+            "model": self.model,
+            "backend": self.backend,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "timeout": self.client.timeout,
+            "reasoning_effort": self.reasoning_effort,
+            "stream": self.stream,
+        }
+        for key, val in current.items():
+            merged.setdefault(key, val)
+        for key in (
+            "base_url",
+            "api_key",
+            "model",
+            "backend",
+            "temperature",
+            "max_tokens",
+            "timeout",
+            "reasoning_effort",
+            "stream",
+        ):
+            if key in profile and profile[key] is not None:
+                merged[key] = profile[key]
+        self.client.base_url = str(merged["base_url"]).rstrip("/")
+        self.client.api_key = merged["api_key"]
+        self.client.model = merged["model"]
+        self.model = merged["model"]
+        self.store.model = merged["model"]
+        self.backend = merged["backend"]
+        self.store.backend = merged["backend"]
+        self.temperature = merged["temperature"]
+        self.max_tokens = merged["max_tokens"]
+        if hasattr(self.client, "set_timeout"):
+            self.client.set_timeout(merged["timeout"])
+        else:
+            self.client.timeout = merged["timeout"]
+        self.reasoning_effort = merged["reasoning_effort"]
+        self.stream = merged["stream"]
+        return True, f"switched to {name} ({self.model})"
+
     # ------------------------------------------------------------------
     # direct commands: compact / summary (no agent loop)
     # ------------------------------------------------------------------

python_agent_harness/cli.py

@@ -90,6 +90,13 @@ def make_session(
     # over the config file for the whole session, sub-agents included
     # (same precedence as the main agent's stream).
     effective_stream = settings["stream"] if stream is None else stream
+    model_profiles = config.load_models_config(config_path)
+    # Base settings for /model switching: the main llm settings as
+    # resolved at session start (incl. the CLI --model/--no-stream
+    # overrides above), so a profile's unset keys inherit these
+    # instead of values drifted by earlier switches.
+    llm_settings = dict(settings)
+    llm_settings["stream"] = effective_stream
     return AgentSession(
         project_dir=abs_project,
         client=client,
@@ -110,6 +117,9 @@ def make_session(
         context_path=paths.get("context_path"),
         skill_path=paths.get("skill_path"),
         mcp=mcp_config,
+        model_profiles=model_profiles,
+        llm_settings=llm_settings,
+        config_path=config_path,
     )
 
 
@@ -201,6 +211,16 @@ def cmd_config(args: argparse.Namespace) -> int:
         f"reasoning_effort={subagent_settings['reasoning_effort']} "
         f"stream={subagent_settings['stream']} timeout={subagent_settings['timeout']}"
     )
+    # Show model profiles for /model command
+    model_profiles = config.load_models_config(args.path)
+    if model_profiles:
+        print("models:")
+        for name, profile in sorted(model_profiles.items()):
+            model_name = profile.get("model", "(inherited)")
+            base_url = profile.get("base_url", "(inherited)")
+            print(f"  {name}: model={model_name}, base_url={base_url}")
+    else:
+        print("models: (none configured — add a 'models' section to use /model)")
     return 0
 
 

python_agent_harness/client.py

@@ -286,6 +286,18 @@ def _reset_http(self) -> None:
         with contextlib.suppress(Exception):  # best effort
             old.close()
 
+    def set_timeout(self, timeout: float) -> None:
+        """Update the request timeout and recreate the HTTP pool.
+
+        The pool is created once in ``__init__`` with the initial
+        timeout, so changing the attribute alone would not affect
+        in-flight/future requests.  Recreating the pool makes the new
+        timeout apply to subsequent requests immediately (used by
+        /model switching).
+        """
+        self.timeout = timeout
+        self._reset_http()
+
     def _refresh_api_key(
         self,
         cancel_check: Callable[[], bool] | None = None,

python_agent_harness/config.py

@@ -184,6 +184,8 @@
 # Requires the optional `mcp` extra: pip install -e ".[mcp]".
 DEFAULT_MCP: dict = {"servers": {}}
 
+DEFAULT_MODELS: dict = {}
+
 # Sub-agent LLM overrides: every key defaults to None, meaning "inherit
 # the main LLM setting" (mirrors gptel-agent-harness-subagent-model /
 # -backend).  Only the keys the user actually sets differ from the main
@@ -209,6 +211,17 @@
     "reasoning_effort": "medium",
     "stream": true
   }},
+  "models": {{
+    "_comment": "Named LLM profiles for /model switching. Each entry is a full set of LLM settings (base_url, api_key, model, etc.). Use /model in the TUI to switch at runtime.",
+    "deepseek": {{
+      "base_url": "https://api.deepseek.com/v1",
+      "model": "deepseek-chat"
+    }},
+    "openai": {{
+      "base_url": "https://api.openai.com/v1",
+      "model": "gpt-5-mini"
+    }}
+  }},
   "subagent_llm": {{
     "_comment": "Optional overrides for sub-agent (Agent tool) requests, e.g. a cheaper model. Every key is optional; unset keys inherit the main llm settings above.",
     "base_url": null,
@@ -403,5 +416,37 @@ def load_mcp_config(path: str | os.PathLike | None = None) -> MCPConfig:
     return MCPConfig.from_dict(section.get("servers"))
 
 
+def load_models_config(path: str | os.PathLike | None = None) -> dict[str, dict]:
+    """Load named LLM profiles from the config file's ``models`` object.
+
+    Returns a dict mapping profile names to their LLM settings dicts.
+    Each profile is a partial set of DEFAULT_LLM keys (base_url, api_key,
+    model, etc.); unset keys inherit the main ``llm`` settings when the
+    profile is applied.  An empty dict when the file has no ``models``
+    section or it is empty.
+    """
+    import json
+
+    cfg_path = _config_path(path)
+    if not cfg_path.exists():
+        return {}
+    try:
+        with open(cfg_path, "rb") as f:
+            data = json.load(f)
+    except Exception as e:  # noqa: BLE001
+        raise ValueError(f"cannot read config file {cfg_path}: {e}") from e
+    section = data.get("models") or {}
+    if not isinstance(section, dict):
+        raise ValueError(f"config file {cfg_path}: models must be an object")
+    profiles: dict[str, dict] = {}
+    for name, val in section.items():
+        if name.startswith("_"):
+            continue
+        if not isinstance(val, dict):
+            raise ValueError(f"config file {cfg_path}: models.{name} must be an object")
+        profiles[name] = val
+    return profiles
+
+
 def mask_secret(value: str | None) -> str:
     return "****" if value else "(unset)"

python_agent_harness/session_store.py

@@ -111,6 +111,7 @@ def __init__(
         temperature: float | None = None,
         max_tokens: int | None = None,
         tool_names: list[str] | None = None,
+        round_times: list[float] | None = None,
     ) -> None:
         self.project_dir = project_dir
         self.model = model
@@ -123,6 +124,10 @@ def __init__(
         self.file_path: str | None = None
         self.title_pending = False
         self._first_user_msg: str | None = None
+        # wall-clock start times of each round, persisted in the
+        # metadata block so restored sessions keep their round
+        # timestamps (populated by the TUI on each run)
+        self.round_times: list[float] = list(round_times) if round_times else []
         # serializes save vs. apply_title: the rename must never
         # interleave with a save's write+replace, or the conversation
         # would split across two files (a titled stale file plus a
@@ -179,6 +184,9 @@ def metadata_block(self) -> str:
         if self.tool_names:
             names = " ".join(f'"{n}"' for n in self.tool_names)
             lines.append(f";; gptel--tool-names: ({names})")
+        if self.round_times:
+            stamps = " ".join(repr(float(t)) for t in self.round_times)
+            lines.append(f";; python-agent-harness--round-times: {stamps}")
         lines.append(";; End:")
         return "\n".join(lines)