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

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

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.1.9 - 2026-06-02
+
+- Harden agent-facing CLI recovery with examples on root/group help, structured
+  `models` action errors, and next-command hints for invalid output choices.
+- Add side-effect-free previews for `preferences init`, `interrupt`, and
+  `leases release`; add `session show --plain`.
+- Format `terminate`, `collect`, and `artifacts` human output without raw Python
+  dicts while preserving JSON payloads.
+- Ship `python -m agentpool` support and expand CLI regression coverage.
+
+## 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.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.7
+Version: 0.1.9
 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
@@ -131,8 +131,10 @@ agentpool observe <session-id> --wait-for completed,error,question,approval_prom
 agentpool send <session-id> "Continue with the smallest useful check."
 agentpool artifacts <session-id> --json
 agentpool transcript <session-id> --tail-lines 80 --json
+agentpool session show <session-id> --json
 agentpool sessions --recent 10 --json
 agentpool collect <session-id> --json
+agentpool terminate <session-id> --dry-run --json
 agentpool terminate <session-id> --json
 ```
 
@@ -153,6 +155,7 @@ agentpool spawn \
   --isolation worktree
 
 agentpool worktrees list --repo .
+agentpool worktrees cleanup --session-id <session-id> --dry-run --json
 agentpool worktrees cleanup --session-id <session-id>
 ```
 
@@ -164,6 +167,7 @@ requested through `--isolation worktree` or policy configuration.
 
 ```bash
 agentpool usage-summary --refresh --json
+agentpool usage-summary --refresh --no-interactive --json
 agentpool stats --since 7d --json
 agentpool usage-summary --refresh --backend codexbar --json
 agentpool usage-summary --refresh --backend ccusage --provider claude-code --json
@@ -171,17 +175,22 @@ 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.
+refresh. Use `--no-interactive` or `AGENTPOOL_NO_INTERACTIVE_USAGE=1` when a
+shell script must avoid provider TUI fallback probes.
 
 ## Provider Matrix
 

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

@@ -110,8 +110,10 @@ agentpool observe <session-id> --wait-for completed,error,question,approval_prom
 agentpool send <session-id> "Continue with the smallest useful check."
 agentpool artifacts <session-id> --json
 agentpool transcript <session-id> --tail-lines 80 --json
+agentpool session show <session-id> --json
 agentpool sessions --recent 10 --json
 agentpool collect <session-id> --json
+agentpool terminate <session-id> --dry-run --json
 agentpool terminate <session-id> --json
 ```
 
@@ -132,6 +134,7 @@ agentpool spawn \
   --isolation worktree
 
 agentpool worktrees list --repo .
+agentpool worktrees cleanup --session-id <session-id> --dry-run --json
 agentpool worktrees cleanup --session-id <session-id>
 ```
 
@@ -143,6 +146,7 @@ requested through `--isolation worktree` or policy configuration.
 
 ```bash
 agentpool usage-summary --refresh --json
+agentpool usage-summary --refresh --no-interactive --json
 agentpool stats --since 7d --json
 agentpool usage-summary --refresh --backend codexbar --json
 agentpool usage-summary --refresh --backend ccusage --provider claude-code --json
@@ -150,17 +154,22 @@ 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.
+refresh. Use `--no-interactive` or `AGENTPOOL_NO_INTERACTIVE_USAGE=1` when a
+shell script must avoid provider TUI fallback probes.
 
 ## Provider Matrix
 

{agentpool_cli-0.1.7 → agentpool_cli-0.1.9}/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.9/docs/examples.md

@@ -0,0 +1,42 @@
+# Examples
+
+Spawn a fake question worker:
+
+```bash
+agentpool spawn \
+  --provider fake-question \
+  --repo . \
+  --task "Inspect the project and ask one clarifying question." \
+  --isolation read_only
+```
+
+Observe and steer:
+
+```bash
+agentpool observe <session-id> --wait-for question,completed,error --timeout 120 --json
+agentpool send <session-id> "Inspect migrations first. Stay read-only."
+agentpool session show <session-id> --json
+agentpool collect <session-id> --json
+agentpool terminate <session-id> --dry-run --json
+agentpool terminate <session-id>
+```
+
+Read task text from stdin:
+
+```bash
+cat task.md | agentpool spawn --provider <provider-id> --repo . --stdin --json
+```
+
+Run usage probes without provider TUI fallbacks:
+
+```bash
+AGENTPOOL_NO_INTERACTIVE_USAGE=1 agentpool usage-summary --refresh --json
+agentpool usage --provider claude-code --no-interactive --json
+```
+
+Preview worktree cleanup before removing anything:
+
+```bash
+agentpool worktrees cleanup --session-id <session-id> --dry-run --json
+agentpool worktrees cleanup --session-id <session-id> --force --json
+```

{agentpool_cli-0.1.7 → agentpool_cli-0.1.9}/docs/quickstart.md

@@ -29,8 +29,12 @@ cycle. `"ok": true` means the control plane works end to end.
 ```bash
 agentpool inventory --json
 agentpool usage-summary --json          # add --refresh for live probes
+agentpool usage-summary --refresh --no-interactive --json
 ```
 
+Use `--no-interactive` or `AGENTPOOL_NO_INTERACTIVE_USAGE=1` for scripts that
+must avoid provider TUI fallback probes.
+
 ## 4. Run a real worker (explicit provider + isolation)
 
 ```bash
@@ -44,7 +48,9 @@ The result includes a top-level `session_id`. Drive it with:
 ```bash
 agentpool observe <session-id> --wait-for question,completed,error --timeout 120 --json
 agentpool send <session-id> "Continue with the smallest useful check." --json
+agentpool session show <session-id> --json
 agentpool collect <session-id> --json
+agentpool terminate <session-id> --dry-run --json
 agentpool terminate <session-id> --json
 ```
 

{agentpool_cli-0.1.7 → agentpool_cli-0.1.9}/docs/security.md

@@ -16,8 +16,10 @@ Guardrails:
   key, URI-password, JWT, and private-key patterns.
 
 Live usage probes are explicit. `inventory` does not run provider TUIs or
-network quota probes. `usage --refresh` and `usage-summary --refresh` may read
-existing CLI auth state and contact provider APIs, depending on the provider.
+network quota probes. `usage` and `usage-summary --refresh` may read existing
+CLI auth state and contact provider APIs, depending on the provider. Use
+`--no-interactive` or `AGENTPOOL_NO_INTERACTIVE_USAGE=1` when automation must
+avoid provider TUI fallback probes.
 
 Worker output is an untrusted channel. CLI and MCP observe/collect paths return
 summary metadata by default; inline excerpts and transcript/event resources are

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

@@ -4,16 +4,23 @@ Usage is best effort and confidence-tagged. Unknown is valid.
 
 Allowed confidence values include `official`, `local_cli`, `local_config`, `provider_warning`, `observed`, `user_configured`, and `unknown`. AgentPool does not fabricate exact quotas and does not scrape browser sessions in v0.1.
 
-Live probes are only run by explicit usage requests. Inventory remains non-invasive and reports whether a provider supports an explicit usage probe. Successful explicit probes are persisted to SQLite; `agentpool usage --cached`, `get_usage_summary(refresh=false)`, and `get_usage_snapshot(refresh=false)` read the latest persisted snapshots without refreshing providers. MCP refreshes do not run interactive provider TUI probes, because those can interfere with the host agent that is calling AgentPool. MCP refreshes are also bounded by a short server-side budget; if a provider is slow, AgentPool returns a partial response with an unknown row instead of holding the MCP connection open.
+Live probes are only run by explicit usage requests. Inventory remains non-invasive and reports whether a provider supports an explicit usage probe. Successful explicit probes are persisted to SQLite; `agentpool usage --cached`, `get_usage_summary(refresh=false)`, and `get_usage_snapshot(refresh=false)` read the latest persisted snapshots without refreshing providers. MCP refreshes do not run interactive provider TUI probes, because those can interfere with the host agent that is calling AgentPool. CLI callers can use `--no-interactive` on `usage` / `usage-summary`, or set `AGENTPOOL_NO_INTERACTIVE_USAGE=1`, to take the same headless posture. MCP refreshes are also bounded by a short server-side budget; if a provider is slow, AgentPool returns a partial response with an unknown row instead of holding the MCP connection open.
 
 `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.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.7"
+version = "0.1.9"
 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.9}/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.9",
   "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.9",
       "transport": {
         "type": "stdio"
       },

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

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

agentpool_cli-0.1.9/src/agentpool/__main__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from agentpool.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()