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

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

@@ -2,6 +2,23 @@
 
 ## 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.
+  Git, tmux client operations, provider detection, Cursor status checks, Codex
+  app-server probes, and external usage helpers now detach from the host TTY by
+  default.
+- Add a subprocess-safety regression test so new product code cannot introduce
+  raw `subprocess.run`/`Popen` calls outside the shared utility.
+
 ## 0.1.6 - 2026-06-01
 
 - Run external usage helper commands in isolated, non-interactive subprocess

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.6
+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.6 → 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.6 → 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.6 → 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.6 → agentpool_cli-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.6"
+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.6 → 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.6",
+  "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.6",
+      "version": "0.1.8",
       "transport": {
         "type": "stdio"
       },

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

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

{agentpool_cli-0.1.6 → 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.6 → agentpool_cli-0.1.8}/src/agentpool/git_worktree.py

@@ -1,6 +1,4 @@
 from __future__ import annotations
-
-import subprocess
 from pathlib import Path
 
 from agentpool.models import ToolError
@@ -41,12 +39,9 @@ def create_worktree(repo_path: Path, provider_id: str, session_id: str) -> Path:
     parent.mkdir(parents=True, exist_ok=True)
     worktree_path = parent / session_id
     branch = agentpool_branch(provider_id, session_id)
-    proc = subprocess.run(
+    proc = run_capture(
         ["git", "worktree", "add", "-b", branch, str(worktree_path)],
-        cwd=str(repo_path),
-        text=True,
-        capture_output=True,
-        check=False,
+        cwd=repo_path,
     )
     if proc.returncode != 0:
         raise ToolError(
@@ -66,12 +61,9 @@ def delete_agentpool_branch(repo_path: Path, provider_id: str, session_id: str)
     if not is_git_repo(repo_path):
         return {"deleted": False, "reason": "not_git_repo"}
     branch = agentpool_branch(provider_id, session_id)
-    proc = subprocess.run(
+    proc = run_capture(
         ["git", "branch", "-D", branch],
-        cwd=str(repo_path),
-        text=True,
-        capture_output=True,
-        check=False,
+        cwd=repo_path,
     )
     if proc.returncode != 0:
         return {"deleted": False, "branch": branch, "stderr": proc.stderr.strip()}
@@ -81,12 +73,9 @@ def delete_agentpool_branch(repo_path: Path, provider_id: str, session_id: str)
 def list_agentpool_worktrees(repo_path: Path) -> list[dict[str, str | bool]]:
     if not is_git_repo(repo_path):
         return []
-    proc = subprocess.run(
+    proc = run_capture(
         ["git", "worktree", "list", "--porcelain"],
-        cwd=str(repo_path),
-        text=True,
-        capture_output=True,
-        check=False,
+        cwd=repo_path,
     )
     if proc.returncode != 0:
         return []
@@ -128,7 +117,7 @@ def cleanup_worktree(repo_path: Path, worktree_path: Path, force: bool = False)
     if force:
         args.append("--force")
     args.append(str(worktree_path))
-    proc = subprocess.run(args, cwd=str(repo_path), text=True, capture_output=True, check=False)
+    proc = run_capture(args, cwd=repo_path)
     if proc.returncode != 0:
         raise ToolError(
             "WORKTREE_CLEANUP_FAILED",

{agentpool_cli-0.1.6 → 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.6 → 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.6 → agentpool_cli-0.1.8}/src/agentpool/runtimes/tmux.py

@@ -3,10 +3,10 @@ from __future__ import annotations
 import os
 import signal
 import shutil
-import subprocess
 from pathlib import Path
 
 from agentpool.models import RuntimeKind, TmuxSessionRef, ToolError
+from agentpool.utils import run_capture
 
 
 class TmuxRuntime:
@@ -28,29 +28,22 @@ class TmuxRuntime:
         merged_env = os.environ.copy()
         if env:
             merged_env.update(env)
-        try:
-            subprocess.run(
-                [tmux, "new-session", "-d", "-s", session_name, "-c", str(cwd), *command],
-                env=merged_env,
-                text=True,
-                capture_output=True,
-                check=True,
-            )
-        except subprocess.CalledProcessError as exc:
+        proc = run_capture(
+            [tmux, "new-session", "-d", "-s", session_name, "-c", str(cwd), *command],
+            env=merged_env,
+        )
+        if proc.returncode != 0:
             raise ToolError(
                 "SPAWN_FAILED",
                 f"Failed to create tmux session {session_name}.",
-                {"stderr": exc.stderr, "stdout": exc.stdout, "command": command},
-            ) from exc
+                {"stderr": proc.stderr, "stdout": proc.stdout, "command": command},
+            )
         return TmuxSessionRef(session_name=session_name)
 
     def capture(self, ref: TmuxSessionRef, lines: int = 300) -> str:
         tmux = self.require_tmux()
-        proc = subprocess.run(
+        proc = run_capture(
             [tmux, "capture-pane", "-p", "-J", "-t", ref.target, "-S", f"-{lines}"],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         if proc.returncode != 0:
             raise ToolError(
@@ -66,18 +59,27 @@ class TmuxRuntime:
             return
         tmux = self.require_tmux()
         buffer_name = f"agentpool-{ref.session_name}"
-        subprocess.run([tmux, "load-buffer", "-b", buffer_name, "-"], input=text, text=True, check=True)
-        subprocess.run([tmux, "paste-buffer", "-b", buffer_name, "-t", ref.target], check=True)
+        load = run_capture([tmux, "load-buffer", "-b", buffer_name, "-"], input_text=text)
+        if load.returncode != 0:
+            raise ToolError(
+                "TMUX_SEND_FAILED",
+                f"Could not load tmux paste buffer for {ref.target}.",
+                {"stderr": load.stderr},
+            )
+        paste = run_capture([tmux, "paste-buffer", "-b", buffer_name, "-t", ref.target])
+        if paste.returncode != 0:
+            raise ToolError(
+                "TMUX_SEND_FAILED",
+                f"Could not paste tmux buffer to {ref.target}.",
+                {"stderr": paste.stderr},
+            )
         if submit and not text.endswith("\n"):
             self.send_keys(ref, ["Enter"])
 
     def send_keys(self, ref: TmuxSessionRef, keys: list[str]) -> None:
         tmux = self.require_tmux()
-        proc = subprocess.run(
+        proc = run_capture(
             [tmux, "send-keys", "-t", ref.target, *keys],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         if proc.returncode != 0:
             raise ToolError(
@@ -95,7 +97,7 @@ class TmuxRuntime:
     def terminate(self, ref: TmuxSessionRef) -> None:
         tmux = self.require_tmux()
         pgid = self._pane_process_group(ref)
-        subprocess.run([tmux, "kill-session", "-t", ref.session_name], check=False)
+        run_capture([tmux, "kill-session", "-t", ref.session_name])
         if pgid is not None:
             try:
                 os.killpg(pgid, signal.SIGTERM)
@@ -107,22 +109,16 @@ class TmuxRuntime:
     def exists(self, ref: TmuxSessionRef) -> bool:
         if not self.tmux_binary:
             return False
-        proc = subprocess.run(
+        proc = run_capture(
             [self.tmux_binary, "has-session", "-t", ref.session_name],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         return proc.returncode == 0
 
     def _pane_process_group(self, ref: TmuxSessionRef) -> int | None:
         if not self.tmux_binary:
             return None
-        proc = subprocess.run(
+        proc = run_capture(
             [self.tmux_binary, "display-message", "-p", "-t", ref.target, "#{pane_pid}"],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         if proc.returncode != 0:
             return None

{agentpool_cli-0.1.6 → 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.6 → 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.6 → agentpool_cli-0.1.8}/src/agentpool/usage/_common.py

@@ -17,6 +17,7 @@ import certifi
 
 from agentpool.models import CapacitySnapshot, Confidence, TmuxSessionRef, UsageStatus, UsageWindow, UsageWindowKind
 from agentpool.runtimes.tmux import TmuxRuntime
+from agentpool.utils import run_capture, terminate_process_group
 
 
 class ProbeError(Exception):
@@ -65,34 +66,12 @@ def _urlopen(
     return urllib.request.urlopen(request, timeout=timeout, context=context)
 
 
-def _probe_env() -> dict[str, str]:
-    env = os.environ.copy()
-    env.update(
-        {
-            "TERM": "dumb",
-            "NO_COLOR": "1",
-            "CLICOLOR": "0",
-            "FORCE_COLOR": "0",
-        }
-    )
-    return env
-
-
 def _run_probe_command(
     command: list[str],
     *,
     timeout: float,
 ) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        command,
-        stdin=subprocess.DEVNULL,
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-        check=False,
-        start_new_session=True,
-        env=_probe_env(),
-    )
+    return run_capture(command, timeout=timeout, terminal_dumb=True)
 
 
 def _request_json(request: urllib.request.Request) -> dict[str, Any]:
@@ -248,12 +227,7 @@ def _clean_optional_string(value: object) -> str | None:
 
 
 def _terminate_process(proc: subprocess.Popen[str]) -> None:
-    if proc.poll() is None:
-        proc.terminate()
-        try:
-            proc.wait(timeout=1)
-        except subprocess.TimeoutExpired:
-            proc.kill()
+    terminate_process_group(proc)
 
 
 def _safe_read_pipe(pipe: Any) -> str:

{agentpool_cli-0.1.6 → agentpool_cli-0.1.8}/src/agentpool/usage/codex.py

@@ -20,6 +20,7 @@ from agentpool.usage._common import (
     unavailable,
     unknown,
 )
+from agentpool.utils import popen_text
 
 
 def codex_cli_usage_snapshot(provider_id: str, binary: str | None = None) -> CapacitySnapshot:
@@ -79,12 +80,9 @@ def parse_codex_rate_limits(provider_id: str, payload: dict[str, Any]) -> Capaci
 
 
 def _codex_rpc_rate_limits(executable: str) -> dict[str, Any]:
-    proc = subprocess.Popen(
+    proc = popen_text(
         [executable, "-s", "read-only", "-a", "untrusted", "app-server"],
-        stdin=subprocess.PIPE,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=True,
+        terminal_dumb=True,
     )
     try:
         _json_rpc_request(proc, 1, "initialize", {"clientInfo": {"name": "agentpool", "version": "0.1.0"}}, 8.0)

{agentpool_cli-0.1.6 → 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: