Release: honor dynamic_rule_interval and add agent_status_interval

Surface configuration for two agent loop intervals that were previously
shadowed by hardcoded 300-second values in guard-agent's _rules_loop and
_status_loop. Both changes documented under the v3.1.0 CHANGELOG entry.

Fixed:

- SecurityConfig.dynamic_rule_interval is now actually honored.
  to_agent_config() previously dropped the field on the floor, so
  guard-agent's _rules_loop ran on a hardcoded 300s regardless of user
  configuration. The value is now forwarded through to
  AgentConfig.dynamic_rule_interval. Effective with guard-agent >= 2.6.0
  (matching field added there).

Added:

- SecurityConfig.agent_status_interval - new int field (default 300,
  range 60-86400) controlling how often the agent reports its status to
  the SaaS dashboard. Forwarded to AgentConfig.status_interval. Pairs
  with guard-agent >= 2.6.0 which actually honors the value.

Tests:

- Five new cases in tests/test_agent/test_models_agent_integration.py
  covering forwarding of both interval fields, default value,
  lower-bound rejection (60), and upper-bound rejection (86400).

Author: rennf93

CHANGELOG.md

@@ -24,6 +24,7 @@ Production reliability + ergonomics: NOSCRIPT recovery, lazy_init by default, cl
 - **Cloud-IP store class-as-factory resolution.** `HandlerInitializer._resolve_cloud_ip_store` now treats a bare class object (e.g. `cloud_ip_store=RedisCloudIpStore`) as a factory and invokes it with `redis_handler`, instead of mistaking it for an instance via `isinstance(cls, Protocol)` (which returns `True` for runtime-checkable protocol classes).
 - **Lazy-init partial-failure isolation.** `_run_lazy_init` previously wrapped both cloud-IP and geo-IP initialization in a single `try` — a cloud failure permanently disabled geo init. Each is now wrapped independently so a transient cloud-API outage no longer blocks geo lookups. With `lazy_init=True` now the default, this prevents silent loss of geo enforcement.
 - **PR #19 fallout cleanup.** Cleared 14 ruff F821/UP037 errors and 5 mypy errors that PR #19 left behind: missing `Literal` imports in both decorator base files, narrow-type assignment in `dynamic_rule_handler`, and invariant-`set` argument-type mismatches at `cloud_handler.initialize_redis` call sites in both async and sync `handler_initializer`.
+- **`SecurityConfig.dynamic_rule_interval` is now actually honored.** `to_agent_config()` previously dropped this field on the floor; the agent's `_rules_loop` ran on a hardcoded 300s regardless of what users configured. Fixed by forwarding the value through to `AgentConfig.dynamic_rule_interval`. Effective once `guard-agent >= 2.6.0` is installed (the agent side adds the matching field).
 
 ### Changed
 
@@ -36,6 +37,7 @@ Production reliability + ergonomics: NOSCRIPT recovery, lazy_init by default, cl
 - **`cloud_ip_store` accepts a `CloudIpStoreFactory` callable** (`Callable[[RedisHandlerProtocol], CloudIpStoreProtocol]`), letting users defer store construction until the Redis handler is built. Eliminates the chicken-and-egg pattern of constructing a throwaway `RedisManager` just to feed `RedisCloudIpStore`. Sync protocol mirror exposes `SyncCloudIpStoreFactory`.
 - **`CloudProvider` Literal alias and `VALID_CLOUD_PROVIDERS` frozenset** exported from `guard_core.models`. Type alias with single source of truth: `CloudProvider = Literal["AWS", "GCP", "Azure"]`; runtime guard set: `VALID_CLOUD_PROVIDERS = frozenset(get_args(CloudProvider))`.
 - **`rate_limit_script_reloaded` SecurityEvent** emitted on NOSCRIPT recovery so dashboards can detect repeated reloads (signal of unstable Redis).
+- **`SecurityConfig.agent_status_interval`** — new `int` field (default 300, range 60-86400) controlling how often the agent reports its status to the SaaS dashboard. Forwarded to `AgentConfig.status_interval`. Pairs with `guard-agent >= 2.6.0` which actually honors the value (the agent previously hardcoded 300).
 
 ___
 

docs/release-notes.md

@@ -29,6 +29,7 @@ Production reliability + ergonomics: NOSCRIPT recovery, lazy_init by default, cl
 - **Cloud-IP store class-as-factory resolution.** `HandlerInitializer` now treats a bare class object passed via `cloud_ip_store=RedisCloudIpStore` as a factory and invokes it with `redis_handler`.
 - **Lazy-init partial-failure isolation.** `_run_lazy_init` wraps cloud-IP and geo-IP initialization in independent `try` blocks so a cloud failure no longer disables geo init. Important now that `lazy_init=True` is the default.
 - **PR #19 fallout cleanup.** Cleared 14 ruff F821/UP037 errors and 5 mypy errors left behind by PR #19.
+- **`SecurityConfig.dynamic_rule_interval` is now actually honored.** `to_agent_config()` previously dropped this field on the floor; the agent's `_rules_loop` ran on a hardcoded 300s regardless of what users configured. Fixed by forwarding the value through to `AgentConfig.dynamic_rule_interval`. Effective once `guard-agent >= 2.6.0` is installed.
 
 ### Changed
 
@@ -41,6 +42,7 @@ Production reliability + ergonomics: NOSCRIPT recovery, lazy_init by default, cl
 - **`cloud_ip_store` accepts a `CloudIpStoreFactory` callable** (`Callable[[RedisHandlerProtocol], CloudIpStoreProtocol]`). Sync mirror exposes `SyncCloudIpStoreFactory`.
 - **`CloudProvider` Literal alias and `VALID_CLOUD_PROVIDERS` frozenset** exported from `guard_core.models`.
 - **`rate_limit_script_reloaded` SecurityEvent** emitted on NOSCRIPT recovery.
+- **`SecurityConfig.agent_status_interval`** — new `int` field (default 300, range 60-86400) controlling how often the agent reports its status to the SaaS dashboard. Forwarded to `AgentConfig.status_interval`. Pairs with `guard-agent >= 2.6.0` which actually honors the value (the agent previously hardcoded 300).
 
 ___
 

guard_core/models.py

@@ -376,6 +376,13 @@ class SecurityConfig(BaseModel):
         default=300, description="Interval in seconds between dynamic rule updates"
     )
 
+    agent_status_interval: int = Field(
+        default=300,
+        ge=60,
+        le=86400,
+        description="Interval in seconds between agent status reports to the SaaS",
+    )
+
     emergency_mode: bool = Field(
         default=False, description="Emergency lockdown mode (set by dynamic rules)"
     )
@@ -697,6 +704,8 @@ def to_agent_config(self) -> "AgentConfig | None":
                 project_id=self.agent_project_id,
                 buffer_size=self.agent_buffer_size,
                 flush_interval=self.agent_flush_interval,
+                dynamic_rule_interval=self.dynamic_rule_interval,
+                status_interval=self.agent_status_interval,
                 enable_events=self.agent_enable_events,
                 enable_metrics=self.agent_enable_metrics,
                 timeout=self.agent_timeout,

tests/test_agent/test_models_agent_integration.py

@@ -177,3 +177,67 @@ def test_valid_agent_and_dynamic_rules_config() -> None:
     assert config.enable_agent is True
     assert config.enable_dynamic_rules is True
     assert config.dynamic_rule_interval == 600
+
+
+def test_to_agent_config_forwards_dynamic_rule_interval() -> None:
+    """`dynamic_rule_interval` was added to AgentConfig in guard-agent 2.6.0.
+
+    Asserted at the call-site contract level — to_agent_config() must pass
+    dynamic_rule_interval as a kwarg to AgentConfig. Older installed agents
+    silently drop unknown kwargs.
+    """
+    import guard_agent
+
+    config = SecurityConfig(
+        enable_agent=True,
+        agent_api_key="test-key",
+        dynamic_rule_interval=600,
+    )
+
+    spy = MagicMock(name="AgentConfig")
+    with patch.object(guard_agent, "AgentConfig", spy):
+        config.to_agent_config()
+
+    spy.assert_called_once()
+    assert spy.call_args.kwargs.get("dynamic_rule_interval") == 600
+
+
+def test_to_agent_config_forwards_agent_status_interval() -> None:
+    """`status_interval` was added to AgentConfig in guard-agent 2.6.0.
+
+    Asserted at the call-site contract level — to_agent_config() must pass
+    status_interval as a kwarg to AgentConfig.
+    """
+    import guard_agent
+
+    config = SecurityConfig(
+        enable_agent=True,
+        agent_api_key="test-key",
+        agent_status_interval=900,
+    )
+
+    spy = MagicMock(name="AgentConfig")
+    with patch.object(guard_agent, "AgentConfig", spy):
+        config.to_agent_config()
+
+    spy.assert_called_once()
+    assert spy.call_args.kwargs.get("status_interval") == 900
+
+
+def test_agent_status_interval_defaults_to_300() -> None:
+    config = SecurityConfig()
+    assert config.agent_status_interval == 300
+
+
+def test_agent_status_interval_rejects_below_60() -> None:
+    from pydantic import ValidationError
+
+    with pytest.raises(ValidationError):
+        SecurityConfig(agent_status_interval=30)
+
+
+def test_agent_status_interval_rejects_above_86400() -> None:
+    from pydantic import ValidationError
+
+    with pytest.raises(ValidationError):
+        SecurityConfig(agent_status_interval=86401)