agentpool-cli 0.1.7__tar.gz → 0.1.8__tar.gz

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.1.8 - 2026-06-01
+
+- Treat stale usage snapshots as age metadata, not as an unusable-provider
+  reason. `usage-summary` still reports `stale` and `age_seconds`, but a stale
+  cache entry no longer overrides usable quota/status data.
+- Add optional `policy.usage_auto_refresh_after_seconds` for users who want
+  cached usage summaries to refresh automatically after a configured age.
+
 ## 0.1.7 - 2026-06-01
 
 - Centralize non-interactive subprocess execution behind terminal-safe helpers.

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.7
+Version: 0.1.8
 Summary: Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom.
 Author: AgentPool contributors
 License-Expression: MIT
@@ -171,14 +171,18 @@ agentpool usage-summary --refresh --backend ccusage --provider claude-code --jso
 
 `usage-summary` returns a `providers` object keyed by provider id. It is not
 ordered and it is not a recommendation list. Each row includes `usable`,
-`unusable_reason`, quota windows, confidence, staleness, and reset timing when
+`unusable_reason`, quota windows, confidence, age/staleness, and reset timing when
 the provider exposes it. The older CLI `capacity-summary` command is retained
 as a human convenience alias; the MCP surface only exposes `get_usage_snapshot`
 and the opt-in `get_usage_summary` tool.
 
 The default buffer is `policy.min_remaining_percent = 10`. If any reported
 quota window is below that buffer, the provider row is marked unusable for the
-summary. AgentPool still does not pick an alternative provider for you.
+summary. Staleness is reported as age information only; it does not by itself
+make a provider unusable. If you want cached summary reads to refresh
+automatically after a threshold, set `policy.usage_auto_refresh_after_seconds`
+in `~/.agentpool/config.yaml`.
+AgentPool still does not pick an alternative provider for you.
 MCP usage refreshes are intentionally bounded and may return `partial=true`;
 use the CLI commands above when a shell-capable agent needs a complete live
 refresh.

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/README.md

@@ -150,14 +150,18 @@ agentpool usage-summary --refresh --backend ccusage --provider claude-code --jso
 
 `usage-summary` returns a `providers` object keyed by provider id. It is not
 ordered and it is not a recommendation list. Each row includes `usable`,
-`unusable_reason`, quota windows, confidence, staleness, and reset timing when
+`unusable_reason`, quota windows, confidence, age/staleness, and reset timing when
 the provider exposes it. The older CLI `capacity-summary` command is retained
 as a human convenience alias; the MCP surface only exposes `get_usage_snapshot`
 and the opt-in `get_usage_summary` tool.
 
 The default buffer is `policy.min_remaining_percent = 10`. If any reported
 quota window is below that buffer, the provider row is marked unusable for the
-summary. AgentPool still does not pick an alternative provider for you.
+summary. Staleness is reported as age information only; it does not by itself
+make a provider unusable. If you want cached summary reads to refresh
+automatically after a threshold, set `policy.usage_auto_refresh_after_seconds`
+in `~/.agentpool/config.yaml`.
+AgentPool still does not pick an alternative provider for you.
 MCP usage refreshes are intentionally bounded and may return `partial=true`;
 use the CLI commands above when a shell-capable agent needs a complete live
 refresh.

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/docs/agentpool-skill.md

@@ -27,6 +27,9 @@ need to delegate coding-agent work.
     live refresh. MCP `refresh=true` is bounded and can return `partial=true`
     with unknown rows for slow providers.
 - Treat usage rows as a provider-id map. They are not ordered and not ranked.
+- Treat `stale` and `age_seconds` as age metadata, not as an instruction to
+  avoid a provider. If the user configured usage auto-refresh, cached summary
+  reads may refresh themselves before returning.
 - Inspect provider models before spawning when the model is not already chosen:
   - CLI: `agentpool models --provider <provider-id>`
   - MCP: `get_provider_models(provider_id=...)`

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/docs/usage-detection.md

@@ -9,11 +9,18 @@ Live probes are only run by explicit usage requests. Inventory remains non-invas
 `agentpool usage-summary` returns a `providers` map keyed by provider id. The
 CLI `capacity-summary` command is a human convenience alias; MCP does not expose
 a capacity alias. Each row includes `usable`, `unusable_reason`, `stale`, and
-`age_seconds`. `usable` is conservative: unknown, unauthenticated, unavailable,
-stale, untrusted-confidence, or below-buffer windows are unusable. The default
+`age_seconds`. `stale` is informational age metadata only; it does not by
+itself make a provider unusable. `usable` is derived from install/auth status,
+provider usage status, confidence, and reported quota windows. The default
 buffer is `policy.min_remaining_percent = 10`, and it applies to every reported
 quota window.
 
+Cached summary reads can optionally refresh themselves when old enough. Set
+`policy.usage_auto_refresh_after_seconds` to a non-negative number in
+`~/.agentpool/config.yaml` to refresh `usage-summary` / `get_usage_summary`
+when the cached summary data is missing or older than that threshold. Leave it
+as `null` to keep refreshes explicit.
+
 Usage windows carry a stable `kind` in addition to provider-specific names:
 
 - `daily`

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.7"
+version = "0.1.8"
 description = "Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom."
 readme = "README.md"
 requires-python = ">=3.11"

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sidduHERE/agentpool",
   "title": "AgentPool",
   "description": "See each coding-agent subscription's live limits and offload work to one with headroom.",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "repository": {
     "url": "https://github.com/sidduHERE/agentpool",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "agentpool-cli",
-      "version": "0.1.7",
+      "version": "0.1.8",
       "transport": {
         "type": "stdio"
       },

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/__init__.py

@@ -1,3 +1,3 @@
 """AgentPool local agent control plane."""
 
-__version__ = "0.1.7"
+__version__ = "0.1.8"

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/config.py

@@ -68,6 +68,7 @@ class PolicyConfig(BaseModel):
     default_isolation: str = "read_only"
     min_remaining_percent: int = 10
     usage_stale_after_seconds: int = 1800
+    usage_auto_refresh_after_seconds: int | None = None
     allowed_providers: list[str] = Field(default_factory=list)
     denied_providers: list[str] = Field(default_factory=list)
     block_on_usage_statuses: list[str] = Field(
@@ -326,6 +327,13 @@ def validate_config(config: AgentPoolConfig) -> dict[str, Any]:
         errors.append("policy.allow_auto_routing must stay false in AgentPool v0.1")
     if "auto" in config.providers:
         errors.append("providers.auto is not allowed")
+    if config.policy.usage_stale_after_seconds < 0:
+        errors.append("policy.usage_stale_after_seconds must be non-negative")
+    if (
+        config.policy.usage_auto_refresh_after_seconds is not None
+        and config.policy.usage_auto_refresh_after_seconds < 0
+    ):
+        errors.append("policy.usage_auto_refresh_after_seconds must be non-negative or null")
     if "factory-droid" in config.providers:
         warnings.append("factory-droid is a PRD compatibility name; use droid-cli for the droid binary")
     for provider_id, reason in DEPRECATED_PROVIDER_IDS.items():

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/mcp/tools.py

@@ -68,7 +68,7 @@ def get_usage_summary(
         refresh=refresh,
         backend=backend,
         allow_interactive=False,
-        timeout_seconds=timeout_seconds if refresh else None,
+        timeout_seconds=timeout_seconds,
     )
 
 

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/onboarding.py

@@ -492,7 +492,8 @@ def privacy_doctor(manager: SessionManager) -> dict[str, Any]:
         },
         "usage_refresh": {
             "inventory_runs_live_usage_probes": False,
-            "live_usage_requires_explicit_refresh": True,
+            "live_usage_requires_explicit_refresh": manager.config.policy.usage_auto_refresh_after_seconds is None,
+            "summary_auto_refresh_after_seconds": manager.config.policy.usage_auto_refresh_after_seconds,
             "default_backend": "combined",
             "optional_backends": {
                 "codexbar": detect_codexbar(),

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/session_manager.py

@@ -155,9 +155,22 @@ class SessionManager:
             for snapshot in snapshots:
                 self.store.save_usage_snapshot(snapshot)
             source = "live_probe"
+            summary_backend = backend
         else:
             snapshots = self._configured_usage_snapshots(self.store.latest_usage_snapshots(provider_id), provider_id)
             source = "sqlite_cache"
+            summary_backend = "cache"
+            if self._usage_summary_should_auto_refresh(snapshots, provider_id):
+                snapshots = self.registry.usage(
+                    provider_id,
+                    backend=backend,
+                    allow_interactive=allow_interactive,
+                    timeout_seconds=_remaining_seconds(deadline),
+                )
+                for snapshot in snapshots:
+                    self.store.save_usage_snapshot(snapshot)
+                source = "live_probe"
+                summary_backend = backend
         return {
             **build_usage_summary(
                 snapshots,
@@ -167,7 +180,7 @@ class SessionManager:
             ),
             "preferences": preferences_reference(),
             "source": source,
-            "backend": backend if refresh else "cache",
+            "backend": summary_backend,
             "partial": _has_partial_usage(snapshots) or _has_partial_descriptors(descriptors),
         }
 
@@ -865,6 +878,26 @@ class SessionManager:
         configured = set(self.config.providers)
         return [snapshot for snapshot in snapshots if snapshot.provider_id in configured]
 
+    def _usage_summary_should_auto_refresh(self, snapshots: list[Any], provider_id: str | None = None) -> bool:
+        threshold = self.config.policy.usage_auto_refresh_after_seconds
+        if threshold is None:
+            return False
+        if provider_id and not snapshots:
+            return True
+        if not provider_id:
+            configured = set(self.config.providers)
+            seen = {snapshot.provider_id for snapshot in snapshots}
+            if not configured.issubset(seen):
+                return True
+        now = datetime.now(timezone.utc)
+        for snapshot in snapshots:
+            checked_at = snapshot.checked_at
+            if checked_at.tzinfo is None:
+                checked_at = checked_at.replace(tzinfo=timezone.utc)
+            if max(0.0, (now - checked_at).total_seconds()) > threshold:
+                return True
+        return False
+
     def _enforce_deadline(self, session: AgentSession) -> ObserveWorkerResponse | None:
         deadline_at = session.metadata.get("deadline_at")
         if not deadline_at or not active_state(session.state):

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/stats/compute.py

@@ -457,9 +457,8 @@ def _snapshot_usability(
         }
         for window in snapshot.windows
     ]
-    age_seconds = max(0.0, (at - _ensure_utc(snapshot.checked_at)).total_seconds())
-    stale = age_seconds > stale_after_seconds
-    return _usable_reason(snapshot, windows, min_remaining_percent, descriptor, stale)
+    _ = stale_after_seconds
+    return _usable_reason(snapshot, windows, min_remaining_percent, descriptor)
 
 
 def _is_quota_unusable_reason(reason: str | None) -> bool:

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/src/agentpool/usage/summary.py

@@ -65,7 +65,7 @@ def _provider_summary(
     ]
     age_seconds = max(0.0, (now - snapshot.checked_at).total_seconds())
     stale = age_seconds > stale_after_seconds
-    usable, unusable_reason = _usable_reason(snapshot, windows, min_remaining_percent, descriptor, stale)
+    usable, unusable_reason = _usable_reason(snapshot, windows, min_remaining_percent, descriptor)
     return {
         "provider_id": snapshot.provider_id,
         "status": snapshot.status.value if hasattr(snapshot.status, "value") else str(snapshot.status),
@@ -90,7 +90,6 @@ def _usable_reason(
     windows: list[dict[str, Any]],
     min_remaining_percent: int,
     descriptor: ProviderDescriptor | None,
-    stale: bool,
 ) -> tuple[bool, str | None]:
     if descriptor and not descriptor.installed:
         return False, "not_installed"
@@ -110,8 +109,6 @@ def _usable_reason(
     }
     if confidence not in allowed_confidence:
         return False, f"confidence_{confidence}"
-    if stale:
-        return False, "usage_stale"
     for window in windows:
         remaining = window["remaining_percent"]
         if remaining is not None and remaining < min_remaining_percent:

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/tests/unit/test_models_config_store.py

@@ -842,6 +842,85 @@ def test_cached_usage_summary_filters_removed_provider_aliases(tmp_path: Path) -
     assert "factory-droid" not in provider_ids
 
 
+def test_usage_summary_auto_refresh_is_opt_in_and_bounded(tmp_path: Path) -> None:
+    class RefreshingRegistry:
+        def __init__(self) -> None:
+            self.calls: list[dict[str, object]] = []
+
+        def descriptors(self, include_usage: bool = False, timeout_seconds: float | None = None):  # type: ignore[no-untyped-def]
+            return []
+
+        def usage(
+            self,
+            provider_id: str | None = None,
+            *,
+            backend: str = "combined",
+            allow_interactive: bool = True,
+            timeout_seconds: float | None = None,
+        ):  # type: ignore[no-untyped-def]
+            self.calls.append(
+                {
+                    "provider_id": provider_id,
+                    "backend": backend,
+                    "allow_interactive": allow_interactive,
+                    "timeout_seconds": timeout_seconds,
+                }
+            )
+            return [
+                CapacitySnapshot(
+                    provider_id="codex-cli",
+                    status=UsageStatus.AVAILABLE,
+                    confidence=Confidence.OFFICIAL,
+                    windows=[
+                        UsageWindow(
+                            name="5h",
+                            kind=UsageWindowKind.FIVE_HOUR,
+                            remaining_percent=90,
+                            confidence=Confidence.OFFICIAL,
+                        )
+                    ],
+                )
+            ]
+
+    config = load_config(Path("__missing_agentpool_config__.yaml"))
+    config.storage = StorageConfig(db_path=str(tmp_path / "agentpool.sqlite"), artifact_root=str(tmp_path / "artifacts"))
+    config.policy.usage_auto_refresh_after_seconds = 1800
+    store = Store(tmp_path / "agentpool.sqlite")
+    store.save_usage_snapshot(
+        CapacitySnapshot(
+            provider_id="codex-cli",
+            status=UsageStatus.AVAILABLE,
+            confidence=Confidence.OFFICIAL,
+            checked_at=now_utc() - timedelta(hours=2),
+            windows=[
+                UsageWindow(
+                    name="5h",
+                    kind=UsageWindowKind.FIVE_HOUR,
+                    remaining_percent=80,
+                    confidence=Confidence.OFFICIAL,
+                )
+            ],
+        )
+    )
+    registry = RefreshingRegistry()
+    manager = SessionManager(config=config, store=store, registry=registry, runtime=RecordingRuntime())  # type: ignore[arg-type]
+
+    summary = manager.usage_summary(provider_id="codex-cli", refresh=False, backend="native", timeout_seconds=7)
+
+    assert summary["source"] == "live_probe"
+    assert summary["backend"] == "native"
+    assert summary["providers"]["codex-cli"]["usable"] is True
+    assert summary["providers"]["codex-cli"]["stale"] is False
+    assert registry.calls == [
+        {
+            "provider_id": "codex-cli",
+            "backend": "native",
+            "allow_interactive": True,
+            "timeout_seconds": pytest.approx(7, abs=0.1),
+        }
+    ]
+
+
 def test_failed_worktree_spawn_rolls_back_worktree_and_branch(tmp_path: Path) -> None:
     repo = tmp_path / "repo"
     repo.mkdir()

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/tests/unit/test_usage_summary_enrichment.py

@@ -120,7 +120,7 @@ def test_usage_summary_auth_install_and_unknown_confidence_block_usable() -> Non
     assert summary["counts"]["usable"] == 0
 
 
-def test_usage_summary_marks_stale_snapshots_unusable() -> None:
+def test_usage_summary_reports_stale_without_blocking_usable() -> None:
     snapshot = CapacitySnapshot(
         provider_id="codex-cli",
         status=UsageStatus.AVAILABLE,
@@ -138,9 +138,10 @@ def test_usage_summary_marks_stale_snapshots_unusable() -> None:
 
     summary = build_usage_summary([snapshot], stale_after_seconds=1800, provider_descriptors=[_descriptor("codex-cli")])
 
-    assert summary["providers"]["codex-cli"]["usable"] is False
-    assert summary["providers"]["codex-cli"]["unusable_reason"] == "usage_stale"
-    assert summary["providers"]["codex-cli"]["stale"] is True
+    row = summary["providers"]["codex-cli"]
+    assert row["usable"] is True
+    assert row["unusable_reason"] is None
+    assert row["stale"] is True
 
 
 def _descriptor(provider_id: str, installed: bool = True, auth_status: str = "authenticated") -> ProviderDescriptor:

{agentpool_cli-0.1.7 → agentpool_cli-0.1.8}/uv.lock

@@ -3,7 +3,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agentpool-cli"
-version = "0.1.7"
+version = "0.1.8"
 source = { editable = "." }
 dependencies = [
     { name = "certifi" },