agentpool-cli 0.1.11__tar.gz → 0.1.12__tar.gz

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.1.12 - 2026-06-06
+
+- Add optional Terminal Control runtime support while keeping tmux as the
+  default worker runtime.
+- Fix Claude Code steering submission by using provider-specific submit keys
+  for both initial prompts and live `send_worker_message` calls.
+- Restore MCP capacity/cache compatibility aliases, add searchable MCP tool
+  descriptions and annotations, and make Cursor Agent CLI detection robust when
+  MCP hosts launch AgentPool with a minimal `PATH`.
+- Add real-provider and fake-provider coverage for tmux and Terminal Control,
+  plus focused regression coverage for MCP aliases and provider binary lookup.
+
 ## 0.1.11 - 2026-06-05
 
 - Refresh provider model catalogs from current Claude Code, Codex, Cursor,

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.11
+Version: 0.1.12
 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
@@ -40,7 +40,7 @@ informed, never automatic.
 
 The v0.1 alpha posture is conservative:
 
-- tmux is the required runtime.
+- tmux is the default runtime; Terminal Control is optional when configured.
 - 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.
@@ -51,8 +51,10 @@ The v0.1 alpha posture is conservative:
 
 - Python 3.11 or newer.
 - tmux on `PATH`.
+- Optional: `termctrl` on `PATH` for the Terminal Control runtime.
 - Git for worktree isolation and diff collection.
-- macOS or Linux. Windows is not a v0.1 target except through WSL-like shells.
+- macOS or Linux for live runtimes. Windows is not a v0.1 target except through
+  WSL-like shells.
 
 ## Install
 
@@ -72,9 +74,21 @@ 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).
+The `agentpool-cli` package installs on macOS, Linux, and Windows, but live
+terminal runtimes are supported on macOS or Linux (Windows via WSL).
+
+Optional Terminal Control config:
+
+```yaml
+runtime:
+  default: tmux
+  terminal_control:
+    enabled: true
+    binary: termctrl
+    session_prefix: agentpool
+    cols: 120
+    rows: 36
+```
 
 Install from source:
 
@@ -185,8 +199,8 @@ agentpool usage-summary --refresh --backend ccusage --provider claude-code --jso
 ordered and it is not a recommendation list. Each row includes `usable`,
 `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.
+as a human convenience alias; MCP also exposes `get_capacity_summary` as a
+compatibility alias for `get_usage_summary`.
 
 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

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/README.md

@@ -19,7 +19,7 @@ informed, never automatic.
 
 The v0.1 alpha posture is conservative:
 
-- tmux is the required runtime.
+- tmux is the default runtime; Terminal Control is optional when configured.
 - 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.
@@ -30,8 +30,10 @@ The v0.1 alpha posture is conservative:
 
 - Python 3.11 or newer.
 - tmux on `PATH`.
+- Optional: `termctrl` on `PATH` for the Terminal Control runtime.
 - Git for worktree isolation and diff collection.
-- macOS or Linux. Windows is not a v0.1 target except through WSL-like shells.
+- macOS or Linux for live runtimes. Windows is not a v0.1 target except through
+  WSL-like shells.
 
 ## Install
 
@@ -51,9 +53,21 @@ 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).
+The `agentpool-cli` package installs on macOS, Linux, and Windows, but live
+terminal runtimes are supported on macOS or Linux (Windows via WSL).
+
+Optional Terminal Control config:
+
+```yaml
+runtime:
+  default: tmux
+  terminal_control:
+    enabled: true
+    binary: termctrl
+    session_prefix: agentpool
+    cols: 120
+    rows: 36
+```
 
 Install from source:
 
@@ -164,8 +178,8 @@ agentpool usage-summary --refresh --backend ccusage --provider claude-code --jso
 ordered and it is not a recommendation list. Each row includes `usable`,
 `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.
+as a human convenience alias; MCP also exposes `get_capacity_summary` as a
+compatibility alias for `get_usage_summary`.
 
 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

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/architecture.md

@@ -15,7 +15,8 @@ Core modules:
 - `models.py`: Pydantic response and persistence models.
 - `config.py`: `~/.agentpool/config.yaml` loader and defaults.
 - `providers/`: conservative CLI detection and launch templates.
-- `runtimes/tmux.py`: required v0.1 runtime.
+- `runtimes/tmux.py`: default worker runtime.
+- `runtimes/terminal_control.py`: optional named-session Terminal Control runtime.
 - `store.py`: SQLite sessions, events, usage snapshots, artifacts, and leases.
 - `session_manager.py`: policy enforcement and worker lifecycle orchestration.
 - `mcp_server.py`: MCP tools and resources.

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/install.md

@@ -1,16 +1,17 @@
 # Install AgentPool
 
 AgentPool is a local CLI and MCP server. Install it on the same machine where
-your coding-agent CLIs are logged in and where `tmux` is available.
+your coding-agent CLIs are logged in and where your selected runtime is
+available.
 
 ## Requirements
 
 - Python 3.11 or newer.
-- `tmux` on `PATH`.
+- `tmux` on `PATH` for the default runtime.
+- Optional: `termctrl` on `PATH` for the Terminal Control runtime.
 - Git on `PATH`.
-- macOS or Linux for the runtime. The `agentpool-cli` package installs on
-  Windows too, but `tmux` is not native there, so Windows is supported only
-  through WSL.
+- macOS or Linux for live runtimes. The `agentpool-cli` package installs on
+  Windows too, but terminal runtimes are supported only through WSL.
 
 ## Install From PyPI
 

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/mcp-tools.md

@@ -32,7 +32,9 @@ The default toolset is the smallest worker lifecycle surface:
 
 - `get_inventory`
 - `get_usage_summary`
+- `get_capacity_summary`
 - `get_usage_snapshot`
+- `get_cached_usage_snapshot`
 - `get_provider_models`
 - `get_delegation_preferences`
 - `spawn_worker`
@@ -44,11 +46,10 @@ The default toolset is the smallest worker lifecycle surface:
 - `read_worker_transcript`
 - `terminate_worker`
 
-Removed MCP aliases:
+Compatibility aliases:
 
-- `send_message`
-- `get_capacity_summary`
-- `get_cached_usage_snapshot`
+- `get_capacity_summary`: alias for `get_usage_summary`
+- `get_cached_usage_snapshot`: alias for `get_usage_snapshot(refresh=false)`
 
 Use `get_usage_summary(refresh=false)` for the compact provider-capacity view.
 Use `get_usage_snapshot(refresh=false)` only when you need raw snapshots; cached

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/model-catalog.md

@@ -23,7 +23,7 @@ Each provider entry can describe:
 - `model_selection`: non-flag pinning mode, such as Droid runtime settings.
 - `reasoning_effort_arg`: the CLI flag used by providers with native effort
   selection, such as Claude Code `--effort` or Droid `--reasoning-effort`.
-- `submit_keys`: tmux keys needed for interactive submit quirks.
+- `submit_keys`: runtime keys needed for interactive submit quirks.
 - `quirks`: operator-facing notes for harness behavior.
 
 ## Override

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/provider-adapters.md

@@ -8,7 +8,8 @@ Default real-provider behavior is intentionally limited:
 - Probe version with a short timeout.
 - Report auth as `unknown` unless a safe probe exists.
 - Report usage as `unknown` unless a safe explicit probe exists.
-- Launch through tmux using the provider's normal CLI command.
+- Launch through the selected runtime using the provider's normal CLI command;
+  tmux is the default runtime and Terminal Control is optional.
 - Pin a requested model only when the provider exposes a safe process-local
   mechanism for it.
 
@@ -50,12 +51,17 @@ Model pinning behavior:
   `--reasoning-effort`, which AgentPool forwards when requested.
 - AgentPool does not edit or persist provider credentials or user defaults.
 
-Tmux submit behavior:
+Runtime submit behavior:
 
 - Most providers submit pasted text with terminal Enter.
 - `codex-cli` submits with `C-m` in tmux.
+- `claude-code` receives an explicit `Enter` after pasted steering so
+  multi-line messages ending in a newline are submitted instead of left in the
+  composer.
 - Short menu selections such as startup trust or update prompts still use normal
   Enter so they do not go through provider composer shortcuts.
+- Terminal Control maps the same submit keys onto its named key vocabulary, for
+  example `C-m` to `enter` and `C-c` to `ctrl-c`.
 
 Fake providers under `src/agentpool/fixtures/fake_agents/` are the executable contract for v0.1.
 They are packaged with AgentPool so `agentpool smoke --provider fake-question`

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/quickstart.md

@@ -20,8 +20,8 @@ agentpool init
 agentpool doctor --deep --privacy
 ```
 
-`doctor` confirms `tmux`, SQLite, and the artifact root, and lists each
-provider's install/auth state.
+`doctor` confirms runtime availability, SQLite, and the artifact root, and lists
+each provider's install/auth state.
 
 ## 2. Smoke test without a real provider
 

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/docs/usage-detection.md

@@ -7,8 +7,9 @@ Allowed confidence values include `official`, `local_cli`, `local_config`, `prov
 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
+CLI `capacity-summary` command and MCP `get_capacity_summary` tool are
+compatibility aliases for `usage-summary` / `get_usage_summary`. Each row
+includes `usable`, `unusable_reason`, `stale`, and
 `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

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.11"
+version = "0.1.12"
 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.11 → agentpool_cli-0.1.12}/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.11",
+  "version": "0.1.12",
   "repository": {
     "url": "https://github.com/sidduHERE/agentpool",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "agentpool-cli",
-      "version": "0.1.11",
+      "version": "0.1.12",
       "transport": {
         "type": "stdio"
       },

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/src/agentpool/__init__.py

@@ -1,3 +1,3 @@
 """AgentPool local agent control plane."""
 
-__version__ = "0.1.11"
+__version__ = "0.1.12"

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/src/agentpool/artifacts.py

@@ -13,6 +13,7 @@ from agentpool.utils import repo_hash, sha256_file, write_json
 def create_artifact_dir(root: Path, repo_path: Path, session_id: str) -> Path:
     artifact_dir = root / repo_hash(repo_path) / session_id
     (artifact_dir / "raw" / "tmux-captures").mkdir(parents=True, exist_ok=True)
+    (artifact_dir / "raw" / "terminal-control").mkdir(parents=True, exist_ok=True)
     return artifact_dir
 
 

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/src/agentpool/cli.py

@@ -566,6 +566,8 @@ def _next_command_for_error(exc: ToolError) -> str | None:
         return "agentpool spawn --provider <provider-id> --repo <git-repo-path> --task-stdin --isolation read_only"
     if code == "TMUX_NOT_FOUND":
         return "brew install tmux"
+    if code == "TERMINAL_CONTROL_NOT_FOUND":
+        return "install termctrl, then run agentpool doctor --deep --json"
     if code == "INVALID_WINDOW":
         return "agentpool stats --since 7d --json"
     if code == "INVALID_TRANSCRIPT_RANGE":
@@ -580,7 +582,7 @@ def _next_command_for_error(exc: ToolError) -> str | None:
 @app.command()
 def doctor(
     json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
-    deep: Annotated[bool, typer.Option("--deep", help="Run tmux/sqlite/artifact/cache checks.")] = False,
+    deep: Annotated[bool, typer.Option("--deep", help="Run runtime/sqlite/artifact/cache checks.")] = False,
     privacy: Annotated[
         bool,
         typer.Option("--privacy", help="Show local storage and usage-probe privacy posture."),
@@ -594,9 +596,15 @@ def doctor(
     """
     mgr = manager()
     tmux_path = shutil.which("tmux")
+    termctrl_path = shutil.which(mgr.config.runtime.terminal_control.binary)
     inventory = mgr.inventory(include_usage=True)
     data = {
         "tmux": {"installed": bool(tmux_path), "path": tmux_path},
+        "terminal_control": {
+            "enabled": mgr.config.runtime.terminal_control.enabled,
+            "installed": bool(termctrl_path),
+            "path": termctrl_path,
+        },
         "config_path": str(DEFAULT_CONFIG_PATH),
         "db_path": str(mgr.config.storage.db),
         "artifact_root": str(mgr.config.storage.artifacts),
@@ -618,6 +626,7 @@ def doctor(
             provider["usage"]["status"] if provider.get("usage") else "unknown",
         )
     console.print(f"tmux: {tmux_path or 'missing'}")
+    console.print(f"terminal-control: {termctrl_path or 'missing'}")
     if deep:
         deep_data = data["deep"]
         console.print(f"deep checks: {'ok' if deep_data['ok'] else 'failed'}")
@@ -1513,6 +1522,7 @@ def _print_status_payload(data: dict[str, Any]) -> None:
         "current_state",
         "dry_run",
         "would_interrupt",
+        "would_terminate_runtime",
         "would_terminate_tmux",
         "already_terminated",
         "released",
@@ -1610,7 +1620,10 @@ def spawn(
         str,
         typer.Option("--role", help="Worker role: explorer, reviewer, implementer, tester, or custom."),
     ] = "explorer",
-    runtime: Annotated[str, typer.Option("--runtime", help="Runtime. v0.1 supports tmux only.")] = "tmux",
+    runtime: Annotated[
+        str | None,
+        typer.Option("--runtime", help="Runtime override: tmux or terminal-control. Defaults to config."),
+    ] = None,
     isolation: Annotated[
         str,
         typer.Option(
@@ -1741,7 +1754,7 @@ def observe(
     wait_for: Annotated[str | None, typer.Option("--wait-for", help="Comma-separated events.")] = None,
     timeout: Annotated[int, typer.Option("--timeout")] = 0,
     detail: Annotated[str, typer.Option("--detail", help="Output detail: summary, excerpt, or full.")] = "summary",
-    max_lines: Annotated[int | None, typer.Option("--max-lines", help="tmux capture line limit.")] = None,
+    max_lines: Annotated[int | None, typer.Option("--max-lines", help="Runtime capture line limit.")] = None,
     output: Annotated[
         Path | None,
         typer.Option("--output", "--output-file", help="Write JSON observe payload to this file path."),
@@ -1952,7 +1965,10 @@ def transcript(
 @app.command()
 def terminate(
     session_id: str,
-    dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview termination without killing tmux or updating state.")] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview termination without killing the runtime session or updating state."),
+    ] = False,
     json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
 ) -> None:
     """Terminate a worker.

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/src/agentpool/config.py

@@ -64,9 +64,31 @@ class TmuxConfig(BaseModel):
     idle_seconds: int = 30
 
 
+class TerminalControlArtifactsConfig(BaseModel):
+    save_text: bool = False
+    save_json: bool = True
+    save_svg_on_failure: bool = True
+    save_png_on_failure: bool = False
+    record: bool = False
+
+
+class TerminalControlConfig(BaseModel):
+    enabled: bool = False
+    binary: str = "termctrl"
+    session_prefix: str = "agentpool"
+    capture_lines: int = 300
+    cols: int = 120
+    rows: int = 36
+    settle_ms: int = 100
+    deadline_ms: int = 5000
+    host: str | None = None
+    artifacts: TerminalControlArtifactsConfig = Field(default_factory=TerminalControlArtifactsConfig)
+
+
 class RuntimeConfig(BaseModel):
     default: str = "tmux"
     tmux: TmuxConfig = Field(default_factory=TmuxConfig)
+    terminal_control: TerminalControlConfig = Field(default_factory=TerminalControlConfig)
 
 
 class PolicyConfig(BaseModel):

{agentpool_cli-0.1.11 → agentpool_cli-0.1.12}/src/agentpool/mcp/tools.py

@@ -72,6 +72,20 @@ def get_usage_summary(
     )
 
 
+def get_capacity_summary(
+    manager: SessionManager,
+    provider_id: str | None = None,
+    refresh: bool = False,
+    backend: str = "combined",
+    timeout_seconds: float = MCP_USAGE_REFRESH_TIMEOUT_SECONDS,
+) -> dict[str, Any]:
+    return get_usage_summary(manager, provider_id, refresh, backend, timeout_seconds)
+
+
+def get_cached_usage_snapshot(manager: SessionManager, provider_id: str | None = None) -> dict[str, Any]:
+    return manager.cached_usage_snapshot(provider_id)
+
+
 def get_provider_models(manager: SessionManager, provider_id: str | None = None) -> dict[str, Any]:
     return manager.provider_models(provider_id)