feat(heartbeat): add model override for heartbeat phases

Add gateway.heartbeat.model config option that lets operators run
heartbeat on a different (typically cheaper) model than the agent's
primary model.

When set, both Phase 1 (decision LLM call) and Phase 2 (agent
execution loop) use the override model. When unset, behavior is
unchanged — heartbeat uses the agent's configured model.

This enables cost optimization: e.g. run chat on claude-opus-4 but
heartbeat on claude-sonnet-4 or claude-haiku-3.5.

Config example:
  {
    "gateway": {
      "heartbeat": {
        "model": "anthropic/claude-haiku-3.5"
      }
    }
  }

Author: hussein1362

nanobot/cli/commands.py

@@ -791,13 +791,21 @@ async def on_heartbeat_execute(tasks: str) -> str:
         async def _silent(*_args, **_kwargs):
             pass
 
-        resp = await agent.process_direct(
-            tasks,
-            session_key="heartbeat",
-            channel=channel,
-            chat_id=chat_id,
-            on_progress=_silent,
-        )
+        # Temporarily swap agent model if heartbeat has a model override.
+        hb_model = hb_cfg.model
+        original_model = agent.model
+        if hb_model:
+            agent.model = hb_model
+        try:
+            resp = await agent.process_direct(
+                tasks,
+                session_key="heartbeat",
+                channel=channel,
+                chat_id=chat_id,
+                on_progress=_silent,
+            )
+        finally:
+            agent.model = original_model
 
         # Keep a small tail of heartbeat history so the loop stays bounded
         # without losing all short-term context between runs.
@@ -825,6 +833,7 @@ async def on_heartbeat_notify(response: str) -> None:
         interval_s=hb_cfg.interval_s,
         enabled=hb_cfg.enabled,
         timezone=config.agents.defaults.timezone,
+        heartbeat_model=hb_cfg.model,
     )
 
     if channels.enabled_channels:

nanobot/config/schema.py

@@ -146,6 +146,7 @@ class HeartbeatConfig(Base):
     enabled: bool = True
     interval_s: int = 30 * 60  # 30 minutes
     keep_recent_messages: int = 8
+    model: str | None = None  # Override model for heartbeat (Phase 1 + Phase 2)
 
 
 class ApiConfig(Base):

nanobot/heartbeat/service.py

@@ -60,10 +60,12 @@ def __init__(
         interval_s: int = 30 * 60,
         enabled: bool = True,
         timezone: str | None = None,
+        heartbeat_model: str | None = None,
     ):
         self.workspace = workspace
         self.provider = provider
-        self.model = model
+        self.model = heartbeat_model or model
+        self._agent_model = model
         self.on_execute = on_execute
         self.on_notify = on_notify
         self.interval_s = interval_s

tests/heartbeat/__init__.py

@@ -0,0 +1,100 @@
+"""Tests for heartbeat model override feature."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.config.schema import HeartbeatConfig
+from nanobot.heartbeat.service import HeartbeatService
+
+
+@pytest.fixture
+def mock_provider():
+    provider = MagicMock()
+    provider.chat_with_retry = AsyncMock()
+    return provider
+
+
+@pytest.fixture
+def tmp_workspace(tmp_path: Path) -> Path:
+    hb_file = tmp_path / "HEARTBEAT.md"
+    hb_file.write_text("Check email.\n")
+    return tmp_path
+
+
+class TestHeartbeatModelOverride:
+    """Verify that heartbeat.model overrides the agent model for both phases."""
+
+    def test_config_default_model_is_none(self):
+        cfg = HeartbeatConfig()
+        assert cfg.model is None
+
+    def test_config_accepts_model_string(self):
+        cfg = HeartbeatConfig(model="anthropic/claude-haiku-3.5")
+        assert cfg.model == "anthropic/claude-haiku-3.5"
+
+    def test_service_uses_agent_model_when_no_override(self, mock_provider, tmp_workspace):
+        svc = HeartbeatService(
+            workspace=tmp_workspace,
+            provider=mock_provider,
+            model="anthropic/claude-opus-4",
+        )
+        assert svc.model == "anthropic/claude-opus-4"
+        assert svc._agent_model == "anthropic/claude-opus-4"
+
+    def test_service_uses_heartbeat_model_when_set(self, mock_provider, tmp_workspace):
+        svc = HeartbeatService(
+            workspace=tmp_workspace,
+            provider=mock_provider,
+            model="anthropic/claude-opus-4",
+            heartbeat_model="anthropic/claude-haiku-3.5",
+        )
+        assert svc.model == "anthropic/claude-haiku-3.5"
+        assert svc._agent_model == "anthropic/claude-opus-4"
+
+    @pytest.mark.asyncio
+    async def test_phase1_decide_uses_heartbeat_model(self, mock_provider, tmp_workspace):
+        """Phase 1 LLM call should use the heartbeat model, not agent model."""
+        response = MagicMock()
+        response.should_execute_tools = True
+        response.has_tool_calls = True
+        response.tool_calls = [MagicMock(arguments={"action": "skip", "tasks": ""})]
+        mock_provider.chat_with_retry.return_value = response
+
+        svc = HeartbeatService(
+            workspace=tmp_workspace,
+            provider=mock_provider,
+            model="anthropic/claude-opus-4",
+            heartbeat_model="anthropic/claude-haiku-3.5",
+        )
+
+        action, tasks = await svc._decide("Check email.")
+
+        call_kwargs = mock_provider.chat_with_retry.call_args
+        assert call_kwargs.kwargs.get("model") == "anthropic/claude-haiku-3.5"
+        assert action == "skip"
+
+    @pytest.mark.asyncio
+    async def test_phase1_decide_uses_agent_model_without_override(
+        self, mock_provider, tmp_workspace
+    ):
+        """Without override, Phase 1 should use the agent model."""
+        response = MagicMock()
+        response.should_execute_tools = True
+        response.has_tool_calls = True
+        response.tool_calls = [MagicMock(arguments={"action": "skip", "tasks": ""})]
+        mock_provider.chat_with_retry.return_value = response
+
+        svc = HeartbeatService(
+            workspace=tmp_workspace,
+            provider=mock_provider,
+            model="anthropic/claude-opus-4",
+        )
+
+        await svc._decide("Check email.")
+
+        call_kwargs = mock_provider.chat_with_retry.call_args
+        assert call_kwargs.kwargs.get("model") == "anthropic/claude-opus-4"