agentpool-cli 0.1.0__py3-none-any.whl

agentpool_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: agentpool-cli
+Version: 0.1.0
+Summary: Local MCP-exposed control plane for live coding-agent sessions.
+Author: AgentPool contributors
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: card
+Requires-Dist: pillow>=10; extra == 'card'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentPool
+
+<!-- mcp-name: io.github.sidduhere/agentpool -->
+
+AgentPool is a local Python CLI and MCP server for explicitly controlling coding-agent CLIs as worker sessions.
+
+It is a control plane, not an auto-router. AgentPool exposes live provider, model,
+session, artifact, lease, and best-effort usage/capacity state. The primary
+agent or human still chooses the provider and model explicitly.
+
+The v0.1 alpha posture is conservative:
+
+- tmux is the required runtime.
+- Provider selection is explicit; `provider=auto` is rejected.
+- Usage/capacity summaries are confidence-tagged and keyed by provider id.
+- CodexBar and ccusage are optional usage helpers when installed or configured.
+- AgentPool does not store provider credentials, scrape browser usage pages,
+  rank models, merge code, or push code.
+
+## Requirements
+
+- Python 3.11 or newer.
+- tmux on `PATH`.
+- Git for worktree isolation and diff collection.
+- macOS or Linux. Windows is not a v0.1 target except through WSL-like shells.
+
+## Install
+
+AgentPool publishes to PyPI as `agentpool-cli`; the installed command is
+`agentpool`.
+
+```bash
+uv tool install agentpool-cli      # recommended
+pipx install agentpool-cli         # fallback
+uvx agentpool-cli --help           # zero-install try
+```
+
+Then:
+
+```bash
+agentpool setup codex
+agentpool doctor --deep --privacy
+```
+
+The `agentpool-cli` package installs on macOS, Linux, and Windows, but the
+runtime requires `tmux`, so the supported runtime is macOS or Linux (Windows
+via WSL).
+
+Install from source:
+
+```bash
+git clone https://github.com/sidduHERE/agentpool.git
+cd agentpool
+uv tool install --force .
+```
+
+Or run from a development checkout:
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+```
+
+A GitHub release install (wheel pinned to a tag, no PyPI required) is also
+supported:
+
+```bash
+scripts/install.sh latest
+```
+
+See [docs/install.md](docs/install.md) for first-run, upgrade, and MCP setup
+notes.
+
+## Quickstart
+
+```bash
+agentpool init
+agentpool setup cursor
+agentpool config validate
+agentpool doctor --deep --privacy
+agentpool setup all
+agentpool smoke --provider fake-question --repo . --json
+agentpool inventory --json
+```
+
+Start an explicitly selected read-only worker:
+
+```bash
+agentpool spawn \
+  --provider <provider-id> \
+  --repo . \
+  --task "Inspect the project and ask one clarifying question." \
+  --isolation read_only
+
+agentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 120 --json
+agentpool send <session-id> "Continue with the smallest useful check."
+agentpool artifacts <session-id> --json
+agentpool transcript <session-id> --tail-lines 80 --json
+agentpool sessions --recent 10 --json
+agentpool collect <session-id> --json
+agentpool terminate <session-id> --json
+```
+
+`spawn` defaults `--initial-prompt-mode` to `provider_default`. For Codex CLI
+this resolves to `arg`, which passes the first task as the Codex prompt argument
+instead of relying on a paste-and-submit startup cycle. Codex workers also
+accept process-local overrides such as `--reasoning-effort high` and
+`--service-tier fast`; AgentPool does not edit your Codex config.
+
+For AgentPool-created edit isolation, choose worktrees explicitly:
+
+```bash
+agentpool spawn \
+  --provider <provider-id> \
+  --repo . \
+  --task "Make the small patch." \
+  --role implementer \
+  --isolation worktree
+
+agentpool worktrees list --repo .
+agentpool worktrees cleanup --session-id <session-id>
+```
+
+Worktree isolation is not forced by default. Users often have their own
+worktree setup and cleanup rules, so AgentPool only creates a worktree when
+requested through `--isolation worktree` or policy configuration.
+
+## Usage And Capacity
+
+```bash
+agentpool usage-summary --refresh --json
+agentpool stats --since 7d --json
+agentpool usage-summary --refresh --backend codexbar --json
+agentpool usage-summary --refresh --backend ccusage --provider claude-code --json
+```
+
+`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
+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.
+
+## Provider Matrix
+
+| Provider id | Command | Usage status in v0.1 | Model pinning |
+| --- | --- | --- | --- |
+| `codex-cli` | `codex` | native local app-server rate-limit probe; CodexBar optional | `--model` |
+| `cursor-cli` | `agent` or `cursor-agent` | optional CodexBar Cursor usage; native CLI usage is interactive `/usage` only | `--model` + read-only `--mode ask` |
+| `claude-code` | `claude` | temporary `/usage` probe; ccusage telemetry optional | `--model` |
+| `devin-cli` | `devin` | Devin/Windsurf plan-status API from existing CLI auth, with `/usage` fallback | `--model` |
+| `copilot-cli` | `gh copilot` | GitHub Copilot usage API from env or `gh auth token` | forwarded `--model` |
+| `droid-cli` | `droid` | unknown unless surfaced by future safe probe | process-local settings file |
+| `opencode` | `opencode` | configured adapter; usage unknown in this alpha | catalog-driven |
+
+Compatibility note: the PRD calls Factory's coding product `factory-droid`, but
+AgentPool exposes it as `droid-cli` because the installed command is `droid`.
+Do not add a duplicate `factory-droid` inventory row unless a distinct harness
+appears.
+
+## Privacy Posture
+
+AgentPool is local-first, but usage probes can still be sensitive because they
+read existing CLI auth state and may call provider APIs on explicit refresh.
+
+AgentPool does not:
+
+- store provider credentials;
+- read browser cookies by default;
+- scrape browser dashboards;
+- trigger login flows;
+- silently accept paid overage.
+
+AgentPool does store:
+
+- SQLite session, event, usage snapshot, artifact, and lease metadata;
+- transcript and artifact files under `~/.agentpool/artifacts` by default;
+- generated runtime settings that are not credentials.
+
+Run:
+
+```bash
+agentpool doctor --privacy --json
+```
+
+See [SECURITY.md](SECURITY.md) and
+[docs/usage-detection.md](docs/usage-detection.md).
+
+## MCP
+
+Start the MCP server:
+
+```bash
+agentpool mcp
+agentpool mcp --toolsets default,stats
+AGENTPOOL_MCP_LOCKDOWN=1 agentpool mcp
+```
+
+Example host config:
+
+```bash
+agentpool mcp-config --client generic
+```
+
+```json
+{
+  "mcpServers": {
+    "agentpool": {
+      "command": "agentpool",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Verified install helpers (deeplink or one-liner shell command):
+
+```bash
+agentpool mcp-config --client cursor --absolute-command --install
+agentpool mcp-config --client claude-code --absolute-command --install
+agentpool mcp-config --client codex --absolute-command --install
+agentpool mcp-config --client copilot-cli --absolute-command --install
+```
+
+Raw config generators:
+
+```bash
+agentpool mcp-config --client claude-code --json
+agentpool mcp-config --client codex
+agentpool mcp-config --client cursor
+agentpool mcp-config --client claude-desktop --json
+```
+
+Use `--absolute-command` if the MCP host does not inherit your shell `PATH`.
+Verified per-host steps live in [docs/mcp-clients.md](docs/mcp-clients.md).
+Team templates: [.cursor/mcp.json.example](.cursor/mcp.json.example),
+[.mcp.json.example](.mcp.json.example), and [docs/examples/README.md](docs/examples/README.md).
+MCP Registry draft metadata: [server.json](server.json). It intentionally omits
+package entries until `agentpool-cli` exists on PyPI. Release checklist:
+[docs/release.md](docs/release.md).
+Provider setup guides:
+[Cursor](docs/setup-cursor.md),
+[Cursor Agent CLI](docs/setup-cursor-cli.md),
+[Codex](docs/setup-codex.md),
+[Claude Code](docs/setup-claude-code.md),
+[Copilot](docs/setup-copilot.md),
+[Droid](docs/setup-droid.md), and
+[Devin](docs/setup-devin.md).
+
+MCP-connected agents should read these once on connect:
+
+- `agentpool://onboarding`
+- `agentpool://skill.md`
+
+Then use tools for live operations. The default MCP toolset is deliberately
+small: inventory, usage snapshot, provider models, spawn, observe, send,
+interrupt, collect, artifact manifest, transcript paging, and terminate. Add
+opt-in toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
+
+Coding agents with shell access should prefer the CLI path. It is more
+token-efficient because large worker output stays in artifact files and
+`observe`/`collect` return compact manifests by default. MCP remains first-class
+for MCP-native hosts and no-shell environments. See
+[docs/agent-cli-and-mcp.md](docs/agent-cli-and-mcp.md).
+
+## Development Checks
+
+Development and CI checks are documented in [CONTRIBUTING.md](CONTRIBUTING.md).

agentpool_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,60 @@
+agentpool/__init__.py,sha256=5WG9f-hE7frK7VQqjclM0SJy40Oq22W_FHCH_LMj_SE,66
+agentpool/agent_io.py,sha256=iwpdIAe8j_-vpZbaEghsGwR-w4ZbscaQztwbSZTDbl4,4512
+agentpool/artifacts.py,sha256=7jnPRWOgh-1IVfyJQBDicTEAH4uLWZGd1zPSgQnd4bo,5933
+agentpool/cli.py,sha256=Bv8Kjpibaswc_MiplozB34tLXkv8PgxXhAKtNMlFnJU,46781
+agentpool/config.py,sha256=2YD82HzWVqqldTs14OaW--PS09rILex4-Q9Tuv0EJVs,15427
+agentpool/event_detection.py,sha256=lB_hW-9D1C0SU6CE-_5GnZi4X1KzBlaLshDtCYk9SNM,5472
+agentpool/git_worktree.py,sha256=5ZDN7vb_AhTW1EnmBFsF36T8LxjYRR5Q0rCxdfGDa9Y,5195
+agentpool/mcp_server.py,sha256=KYuBPrcg5uyOx0x3dHaFeXRbIaGDnvJEQuHAFLSQB3Y,20468
+agentpool/models.py,sha256=X2qemGScKq8e_7shQg2WJSbmTR0nMQPiGaM0S0BrB5U,9222
+agentpool/onboarding.py,sha256=wxWocczyvyvNDHq5lqYMp3ZcT17zX_17qrLPjBX69hE,50805
+agentpool/policy.py,sha256=LtiZ7crL4kqJR1I86Hc47RjX7CzCCllKa4U2rZkumDk,2492
+agentpool/provider_model_catalog.json,sha256=Ih7BP09JIkVAIYhN6ytyAgQWRDfXd47wx1khZcAdcVo,25151
+agentpool/redaction.py,sha256=MSFzhrJkYwKTWuJge_af18AOKE7hTR7sj662JWrubGQ,1360
+agentpool/session_manager.py,sha256=ZvD8-ew37IMFxVGQdxfCHRtJrvwokuyPN58gYBnZV3s,45988
+agentpool/store.py,sha256=7JN5NW7Vo4B3xamM8sTQJ3KMV1CMwivBu9APi16IbyM,17440
+agentpool/utils.py,sha256=d84IqAKcOn4qQpN1PaLm0Y4Yl2ClWNGxOp-BYjjvEr4,1671
+agentpool/fixtures/__init__.py,sha256=6I_ogEO1X_VPElwInR8CCoY6QQFsQWlZvPkvEg3IVr0,55
+agentpool/fixtures/fake_agents/__init__.py,sha256=XyLNrIe4iPkDnvsMuy-ciKVnNa2MScTY_W2EEzMSZt4,67
+agentpool/fixtures/fake_agents/fake_approval_agent.py,sha256=aXFoumcWVizuooZGkh20bgQ42ePozJR_36Wa1YLTdUU,356
+agentpool/fixtures/fake_agents/fake_common.py,sha256=UN3AenYOKPS4APYFur3cIOOJS7JYWd7g33EY22CVEgI,1001
+agentpool/fixtures/fake_agents/fake_completed_agent.py,sha256=dr5_UbhDmgnjt3G4BxzTC5FB5ZqGWex-SRzUIZkIexg,266
+agentpool/fixtures/fake_agents/fake_idle_agent.py,sha256=YS72OanxGveZveeeAZKE1lmvaTZIwp9d5C6tE5my5WM,260
+agentpool/fixtures/fake_agents/fake_limit_agent.py,sha256=Ju1riY-nJ1HoUF4vuKdU4qYbWcmmaGSrLrlzrge99FI,314
+agentpool/fixtures/fake_agents/fake_patch_agent.py,sha256=Xxd-CysGX8IlHNrNT8ejA5W7bh8wyDzNqV_FtDpXUR8,425
+agentpool/fixtures/fake_agents/fake_question_agent.py,sha256=Pz_Ju-zu4BlAJtlNI5TF4pTnnmS0azErVO9ae38BLLg,440
+agentpool/mcp/__init__.py,sha256=hOkLtiNCELJe6do0Ravo5bMQZiAL248KCq-npEuQD7o,33
+agentpool/mcp/resources.py,sha256=Bx9_BoqQYT7-gEZiNQeDr-BuWPSlbexVQyFYkLHquDU,2571
+agentpool/mcp/tools.py,sha256=w2Nhp7WSmcQ9g5Tj89GiQpumXKnfwFEikYFB4KMDX1c,8234
+agentpool/providers/__init__.py,sha256=EEgO9tiQaC5hGxalc_X9M-9crDWkqXz_yrNMcK6PzLA,124
+agentpool/providers/base.py,sha256=KafQihIAqZTmvjafhu7M0yn0FSbPDdIeQhXgDs3_P_U,15077
+agentpool/providers/registry.py,sha256=4Krp39MkMrGU4PCZ93-QrogQ81vjoEANI59I4faDYHs,5235
+agentpool/runtimes/__init__.py,sha256=AuwAxrR5juwO8qkRHGi_EYCIUB9EyyIgD30XWvD9sGs,75
+agentpool/runtimes/base.py,sha256=RjJnEChmMrV2OBvBc9EAVAl-T_ROPwnsMh4uZzQcR-4,871
+agentpool/runtimes/tmux.py,sha256=TCXLatnMo21kYr2olMHTxtz3y669vW0QESnnI6dq4aI,4671
+agentpool/stats/__init__.py,sha256=ZMNqlytG0cJYPQe8meukx2AoBP4s2QA0aL4kOWH5Ico,220
+agentpool/stats/card.py,sha256=gg_7oRir_JFzSWQpnvHkzsypUNUl0F1FiAGfVDVAU00,2673
+agentpool/stats/compute.py,sha256=t3fzpn4sZFLjNqRs5TlOEZX5mbwEX6zwPnY0oB41cWQ,17225
+agentpool/stats/queries.py,sha256=wILrH6o9T5b7tXpmz11EH01s4JrmH2QP1kCnLAzEYDc,4849
+agentpool/stats/render.py,sha256=U2-yV0bXnjD_3KEuNQbsyLSyBl7t6oghdWolQpPSo18,3777
+agentpool/stats/window.py,sha256=WjMMzhy488SvpJebVMK4teg8Nqt0zR3TpeNdcHrswm8,2823
+agentpool/usage/__init__.py,sha256=sjEwKbbywxlvYREnDaejDfUZu-TWQw6-i8IcGT31c4M,30
+agentpool/usage/_common.py,sha256=TQOhRj90raLFG9KM6hlZMlpMt3QllZVRiGQU5ZY2sxs,7420
+agentpool/usage/ccusage.py,sha256=83n2xHvHB_5sNQhfI1_Od4qVPqWuGl7nwv-L_GvVVaE,5104
+agentpool/usage/claude.py,sha256=05i6WesSBfmZCrNLi42dDchCilnxqoeve5JO6035AJY,805
+agentpool/usage/codex.py,sha256=NdG10-Cz27Vu0jsmZXIKF3TUxiLqzLLikEdeJxWZH88,7656
+agentpool/usage/codexbar.py,sha256=gOXOzQG7IjJWHK_aZg1BZScGXMWJ9-LHwgOgrUlfFIY,6676
+agentpool/usage/combine.py,sha256=srYsFzYGnmbIT042ARg1QMUMZp1bE5m4bq9XhagwR4U,3237
+agentpool/usage/copilot.py,sha256=oUJk-Uv3YmlAUcSQWT9vPMDpvj0j_IleU6X9_PfSysM,5513
+agentpool/usage/devin.py,sha256=ZPFKLb6JWfN5HFNplsDJMoQHdBym-A-qqp8tCrv6E20,10751
+agentpool/usage/parsers.py,sha256=Sw3ea5REW6dWoJuFtricog-kTmMrDpLpIPf02IYRUsU,1391
+agentpool/usage/probes.py,sha256=ws1mBUSjfbdy2CoxUOn8236MFmuFaKEZLb4GmkqpvFk,1707
+agentpool/usage/provider_parsers.py,sha256=94_g4YfnT9HdwpR58xceCurV2S1jSt85-a5MZXnj_NQ,10523
+agentpool/usage/summary.py,sha256=jBon09R8cxBZZ98RAaSIr3Ex2lGTbxnDJLqfOHNPVJo,7164
+agentpool/docs/agentpool-skill.md,sha256=QnOZudAklb274zIid2BX1YyvtQ5B57Y-JnsXfmx403Y,3779
+agentpool/docs/onboarding.md,sha256=hyPi3D0Dq1dbLXp4zOeYWZSDp3nY2rVOC1Guu8NTBJ8,5374
+agentpool_cli-0.1.0.dist-info/METADATA,sha256=-tLmYNx8wNZs_9pXoGA_9pkd-4qqFksmIuGaYTYiFIM,9523
+agentpool_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentpool_cli-0.1.0.dist-info/entry_points.txt,sha256=9hCreP_0QfS0kDjC0EOWtmiLJhM5DabwjMd4_spgz40,48
+agentpool_cli-0.1.0.dist-info/licenses/LICENSE,sha256=IeRCTpTJE5smTxSJ2Z59iCGmhxQsyO7tlpa3oIqdyyM,1079
+agentpool_cli-0.1.0.dist-info/RECORD,,

agentpool_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentpool_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentpool = agentpool.cli:app

agentpool_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentPool contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.