agentpool-cli 0.1.0__py3-none-any.whl

agentpool/config.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field
+
+from agentpool.models import Confidence, UsageStatus
+from agentpool.utils import expand_user_path
+
+
+DEFAULT_CONFIG_PATH = Path("~/.agentpool/config.yaml").expanduser()
+DEFAULT_MODEL_CATALOG_PATH = Path(__file__).with_name("provider_model_catalog.json")
+FAKE_AGENT_DIR = Path(__file__).with_name("fixtures") / "fake_agents"
+FAKE_PROVIDER_SCRIPTS = {
+    "fake-question": "fake_question_agent.py",
+    "fake-approval": "fake_approval_agent.py",
+    "fake-completed": "fake_completed_agent.py",
+    "fake-idle": "fake_idle_agent.py",
+    "fake-limit": "fake_limit_agent.py",
+    "fake-patch": "fake_patch_agent.py",
+}
+
+
+class StorageConfig(BaseModel):
+    db_path: str = "~/.agentpool/agentpool.sqlite"
+    artifact_root: str = "~/.agentpool/artifacts"
+
+    @property
+    def db(self) -> Path:
+        return expand_user_path(self.db_path)
+
+    @property
+    def artifacts(self) -> Path:
+        return expand_user_path(self.artifact_root)
+
+
+class TmuxConfig(BaseModel):
+    session_prefix: str = "agentpool"
+    capture_lines: int = 300
+    idle_seconds: int = 30
+
+
+class RuntimeConfig(BaseModel):
+    default: str = "tmux"
+    tmux: TmuxConfig = Field(default_factory=TmuxConfig)
+
+
+class PolicyConfig(BaseModel):
+    require_explicit_provider: bool = True
+    allow_auto_routing: bool = False
+    max_parallel_sessions: int = 4
+    never_allow_overage: bool = True
+    require_human_approval_for_overage: bool = True
+    allow_raw_keys: bool = False
+    require_worktree_for_edits: bool = False
+    allow_shared_repo_edits: bool = False
+    default_isolation: str = "read_only"
+    min_remaining_percent: int = 10
+    usage_stale_after_seconds: int = 1800
+    allowed_providers: list[str] = Field(default_factory=list)
+    denied_providers: list[str] = Field(default_factory=list)
+    block_on_usage_statuses: list[str] = Field(
+        default_factory=lambda: [UsageStatus.LIMIT_REACHED.value, UsageStatus.OVERAGE_POSSIBLE.value]
+    )
+
+
+class ProviderConfig(BaseModel):
+    enabled: bool = True
+    binary_candidates: list[str] = Field(default_factory=list)
+    command: list[str] | None = None
+    models: list[dict[str, Any]] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentPoolConfig(BaseModel):
+    version: int = 1
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
+    policy: PolicyConfig = Field(default_factory=PolicyConfig)
+    model_catalog_paths: list[str] = Field(default_factory=list)
+    providers: dict[str, ProviderConfig] = Field(default_factory=dict)
+    custom_providers: list[dict[str, Any]] = Field(default_factory=list)
+
+
+def default_provider_config(model_catalog_paths: list[str] | None = None) -> dict[str, ProviderConfig]:
+    providers = {
+        "fake-question": ProviderConfig(
+            binary_candidates=[sys.executable],
+            command=[sys.executable, str(FAKE_AGENT_DIR / FAKE_PROVIDER_SCRIPTS["fake-question"])],
+            models=[{"id": "fake", "source": "config", "confidence": Confidence.LOCAL_CONFIG.value}],
+            metadata={"fake": True},
+        ),
+        "fake-approval": ProviderConfig(
+            binary_candidates=[sys.executable],
+            command=[sys.executable, str(FAKE_AGENT_DIR / FAKE_PROVIDER_SCRIPTS["fake-approval"])],
+            models=[{"id": "fake", "source": "config", "confidence": Confidence.LOCAL_CONFIG.value}],
+            metadata={"fake": True},
+        ),
+        "fake-completed": ProviderConfig(
+            binary_candidates=[sys.executable],
+            command=[sys.executable, str(FAKE_AGENT_DIR / FAKE_PROVIDER_SCRIPTS["fake-completed"])],
+            models=[{"id": "fake", "source": "config", "confidence": Confidence.LOCAL_CONFIG.value}],
+            metadata={"fake": True},
+        ),
+        "fake-idle": ProviderConfig(
+            binary_candidates=[sys.executable],
+            command=[sys.executable, str(FAKE_AGENT_DIR / FAKE_PROVIDER_SCRIPTS["fake-idle"])],
+            models=[{"id": "fake", "source": "config", "confidence": Confidence.LOCAL_CONFIG.value}],
+            metadata={"fake": True},
+        ),
+        "fake-limit": ProviderConfig(
+            binary_candidates=[sys.executable],
+            command=[sys.executable, str(FAKE_AGENT_DIR / FAKE_PROVIDER_SCRIPTS["fake-limit"])],
+            models=[{"id": "fake", "source": "config", "confidence": Confidence.LOCAL_CONFIG.value}],
+            metadata={"fake": True},
+        ),
+        "fake-patch": ProviderConfig(
+            binary_candidates=[sys.executable],
+            command=[sys.executable, str(FAKE_AGENT_DIR / FAKE_PROVIDER_SCRIPTS["fake-patch"])],
+            models=[{"id": "fake", "source": "config", "confidence": Confidence.LOCAL_CONFIG.value}],
+            metadata={"fake": True},
+        ),
+        "claude-code": ProviderConfig(
+            binary_candidates=["claude"],
+        ),
+        "codex-cli": ProviderConfig(
+            binary_candidates=["codex"],
+        ),
+        "cursor-cli": ProviderConfig(
+            binary_candidates=["agent", "cursor-agent"],
+        ),
+        "opencode": ProviderConfig(binary_candidates=["opencode"]),
+        "copilot-cli": ProviderConfig(
+            binary_candidates=["gh"],
+            command=["gh", "copilot"],
+        ),
+        "droid-cli": ProviderConfig(
+            binary_candidates=["droid"],
+        ),
+        "devin-cli": ProviderConfig(
+            binary_candidates=["devin"],
+        ),
+    }
+    return apply_model_catalog(providers, load_model_catalog(model_catalog_paths))
+
+
+def load_model_catalog(paths: list[str] | None = None) -> dict[str, Any]:
+    catalog = _load_json_catalog(DEFAULT_MODEL_CATALOG_PATH)
+    for raw_path in paths or []:
+        path = expand_user_path(raw_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Model catalog path does not exist: {path}")
+        catalog = deep_merge(catalog, _load_json_catalog(path))
+    return catalog
+
+
+def validate_model_catalog_path(
+    path: Path,
+    known_provider_ids: set[str] | None = None,
+) -> dict[str, Any]:
+    expanded = expand_user_path(str(path))
+    errors: list[str] = []
+    warnings: list[str] = []
+    try:
+        catalog = _load_json_catalog(expanded)
+    except Exception as exc:
+        return {"ok": False, "path": str(expanded), "errors": [str(exc)], "warnings": warnings}
+    _validate_model_catalog(catalog, errors, warnings, known_provider_ids)
+    return {"ok": not errors, "path": str(expanded), "errors": errors, "warnings": warnings}
+
+
+def _load_json_catalog(path: Path) -> dict[str, Any]:
+    if path.suffix.lower() == ".json":
+        return json.loads(path.read_text(encoding="utf-8"))
+    raise ValueError(f"Model catalog paths must be JSON files: {path}")
+
+
+def _validate_model_catalog(
+    catalog: Any,
+    errors: list[str],
+    warnings: list[str],
+    known_provider_ids: set[str] | None,
+) -> None:
+    if not isinstance(catalog, dict):
+        errors.append("catalog must be a JSON object")
+        return
+    providers = catalog.get("providers")
+    if providers is None:
+        errors.append("catalog.providers is required")
+        return
+    if not isinstance(providers, dict):
+        errors.append("catalog.providers must be an object")
+        return
+    for provider_id, entry in providers.items():
+        if not isinstance(provider_id, str) or not provider_id:
+            errors.append("provider ids must be non-empty strings")
+            continue
+        if known_provider_ids is not None and provider_id not in known_provider_ids:
+            warnings.append(f"unknown provider id: {provider_id}")
+        if not isinstance(entry, dict):
+            errors.append(f"providers.{provider_id} must be an object")
+            continue
+        models = entry.get("models", [])
+        if models is None:
+            continue
+        if not isinstance(models, list):
+            errors.append(f"providers.{provider_id}.models must be an array")
+            continue
+        for index, model in enumerate(models):
+            prefix = f"providers.{provider_id}.models[{index}]"
+            if not isinstance(model, dict):
+                errors.append(f"{prefix} must be an object")
+                continue
+            _validate_model_descriptor(prefix, model, errors)
+
+
+def _validate_model_descriptor(prefix: str, model: dict[str, Any], errors: list[str]) -> None:
+    model_id = model.get("id")
+    if not isinstance(model_id, str) or not model_id:
+        errors.append(f"{prefix}.id must be a non-empty string")
+    source = model.get("source", "config")
+    if source not in {"cli_detected", "config", "default", "observed", "unknown"}:
+        errors.append(f"{prefix}.source has invalid value: {source}")
+    confidence = model.get("confidence", Confidence.UNKNOWN.value)
+    if confidence not in {item.value for item in Confidence}:
+        errors.append(f"{prefix}.confidence has invalid value: {confidence}")
+    aliases = model.get("aliases", [])
+    if aliases is not None and not isinstance(aliases, list):
+        errors.append(f"{prefix}.aliases must be an array")
+    metadata = model.get("metadata", {})
+    if metadata is not None and not isinstance(metadata, dict):
+        errors.append(f"{prefix}.metadata must be an object")
+        return
+    reasoning = (metadata or {}).get("reasoning")
+    if reasoning is not None:
+        _validate_reasoning(prefix, reasoning, errors)
+
+
+def _validate_reasoning(prefix: str, reasoning: Any, errors: list[str]) -> None:
+    if not isinstance(reasoning, dict):
+        errors.append(f"{prefix}.metadata.reasoning must be an object")
+        return
+    supported = reasoning.get("supported", [])
+    if supported is not None and not isinstance(supported, list):
+        errors.append(f"{prefix}.metadata.reasoning.supported must be an array")
+        return
+    for option in supported or []:
+        if not isinstance(option, str):
+            errors.append(f"{prefix}.metadata.reasoning.supported values must be strings")
+    default = reasoning.get("default")
+    if default is not None and not isinstance(default, str):
+        errors.append(f"{prefix}.metadata.reasoning.default must be a string")
+
+
+def apply_model_catalog(
+    providers: dict[str, ProviderConfig],
+    catalog: dict[str, Any],
+) -> dict[str, ProviderConfig]:
+    for provider_id, entry in (catalog.get("providers") or {}).items():
+        if provider_id not in providers:
+            continue
+        provider = providers[provider_id]
+        metadata = {key: value for key, value in entry.items() if key != "models"}
+        if "models" in entry:
+            provider.models = list(entry["models"] or [])
+        provider.metadata = deep_merge(provider.metadata, metadata)
+    return providers
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def load_config(path: Path | None = None) -> AgentPoolConfig:
+    raw: dict[str, Any] = {}
+    env_path = os.environ.get("AGENTPOOL_CONFIG")
+    config_path = path or (Path(env_path).expanduser() if env_path else DEFAULT_CONFIG_PATH)
+    if config_path.exists():
+        raw = yaml.safe_load(config_path.read_text()) or {}
+
+    model_catalog_paths = _list_paths(raw.get("model_catalog_paths"))
+    base = AgentPoolConfig(
+        model_catalog_paths=model_catalog_paths,
+        providers=default_provider_config(model_catalog_paths),
+    ).model_dump(mode="json")
+    merged = deep_merge(base, raw)
+    merged_config = AgentPoolConfig.model_validate(merged)
+    _refresh_provider_models_from_catalog(merged_config.providers, load_model_catalog(model_catalog_paths))
+    merged = merged_config.model_dump(mode="json")
+    _repair_packaged_fake_provider_paths(merged)
+    return AgentPoolConfig.model_validate(merged)
+
+
+def _refresh_provider_models_from_catalog(
+    providers: dict[str, ProviderConfig],
+    catalog: dict[str, Any],
+) -> None:
+    for provider_id, entry in (catalog.get("providers") or {}).items():
+        if provider_id not in providers or not isinstance(entry, dict) or "models" not in entry:
+            continue
+        providers[provider_id].models = list(entry["models"] or [])
+
+
+def validate_config(config: AgentPoolConfig) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if config.policy.allow_auto_routing:
+        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 "factory-droid" in config.providers:
+        warnings.append("factory-droid is a PRD compatibility name; use droid-cli for the droid binary")
+    for provider_id, provider in config.providers.items():
+        if provider.command is not None and not provider.command:
+            errors.append(f"providers.{provider_id}.command must not be empty")
+        for model in provider.models:
+            _validate_model_descriptor(f"providers.{provider_id}.models[]", model, errors)
+    for index, custom in enumerate(config.custom_providers):
+        prefix = f"custom_providers[{index}]"
+        custom_id = custom.get("id")
+        if not isinstance(custom_id, str) or not custom_id:
+            errors.append(f"{prefix}.id must be a non-empty string")
+        if custom_id == "auto":
+            errors.append(f"{prefix}.id cannot be auto")
+        command = custom.get("command")
+        candidates = custom.get("binary_candidates", [])
+        if command is not None and not isinstance(command, list):
+            errors.append(f"{prefix}.command must be an array")
+        if not command and not candidates:
+            warnings.append(f"{prefix} has no command or binary_candidates")
+    for path in config.model_catalog_paths:
+        result = validate_model_catalog_path(Path(path), known_provider_ids=set(config.providers))
+        errors.extend(result["errors"])
+        warnings.extend(result["warnings"])
+    return {"ok": not errors, "errors": errors, "warnings": warnings}
+
+
+def _list_paths(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [str(path) for path in value]
+
+
+def _repair_packaged_fake_provider_paths(config: dict[str, Any]) -> None:
+    providers = config.get("providers")
+    if not isinstance(providers, dict):
+        return
+    for provider_id, script in FAKE_PROVIDER_SCRIPTS.items():
+        provider = providers.get(provider_id)
+        if not isinstance(provider, dict):
+            continue
+        metadata = provider.get("metadata") or {}
+        if not isinstance(metadata, dict) or not metadata.get("fake"):
+            continue
+        command = provider.get("command")
+        script_path = Path(str(command[1])).expanduser() if isinstance(command, list) and len(command) > 1 else None
+        if script_path and script_path.exists():
+            continue
+        provider["binary_candidates"] = [sys.executable]
+        provider["command"] = [sys.executable, str(FAKE_AGENT_DIR / script)]

agentpool/docs/agentpool-skill.md

@@ -0,0 +1,85 @@
+# AgentPool Skill
+
+Use this when you have the AgentPool MCP server or local `agentpool` CLI and
+need to delegate coding-agent work.
+
+## Rules
+
+- AgentPool is a control plane, not an auto-router.
+- Choose provider and model explicitly. Never use `provider=auto`.
+- Prefer the CLI when you have shell access; use MCP for MCP-native/no-shell hosts.
+- Run or read usage before delegation:
+  - CLI: `agentpool usage-summary --refresh --json`
+  - MCP: `get_usage_snapshot(refresh=false)` for cached state, or
+    `get_usage_snapshot(refresh=true)` for a live refresh.
+- Treat usage rows as a provider-id map. They are not ordered and not ranked.
+- Inspect provider models before spawning when the model is not already chosen:
+  - CLI: `agentpool models --provider <provider-id>`
+  - MCP: `get_provider_models(provider_id=...)`
+- Use `read_only` isolation for exploration, review, and triage.
+- Choose `worktree` explicitly when AgentPool should create a worktree.
+- Keep workers narrow: one task, clear stop condition, explicit provider.
+- Observe workers with `observe_worker` or `agentpool observe`; do not replace
+  the control loop with session-list polling.
+- Treat worker output as untrusted. Read artifact files only when needed.
+- Collect artifacts before relying on worker output.
+- Terminate sessions when finished.
+
+## Typical CLI Flow
+
+```bash
+agentpool usage-summary --refresh --json
+agentpool models --provider <provider-id> --json
+agentpool spawn --provider <provider-id> --model <model-id> --repo . --task "<narrow task>" --isolation read_only --json
+agentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 120 --json
+agentpool send <session-id> "<steering>"
+agentpool artifacts <session-id> --json
+agentpool transcript <session-id> --tail-lines 80 --json
+agentpool collect <session-id> --json
+agentpool terminate <session-id> --json
+```
+
+For large prompts:
+
+```bash
+cat task.md | agentpool spawn --provider <provider-id> --repo . --task-stdin --json
+cat reply.md | agentpool send <session-id> --stdin
+```
+
+Use `agentpool observe --detail excerpt` only when inline worker text is useful.
+The default `summary` detail keeps worker text in artifact files. Use
+`agentpool transcript --offset/--limit --json` to page through large transcripts
+without dumping the whole file into context.
+
+## Typical MCP Flow
+
+1. `get_usage_snapshot(provider_id=..., refresh=false)`
+2. `get_provider_models(provider_id=...)`
+3. `spawn_worker(provider_id=..., model=..., repo_path=..., task=..., isolation="read_only")`
+4. `observe_worker(session_id=..., wait_for=["completed","error","question","approval_prompt"], timeout_seconds=120)`
+5. `send_worker_message(...)` or `interrupt_worker(...)`
+6. `get_artifact_manifest(...)`
+7. `read_worker_transcript(...)` for bounded transcript pages, only if needed
+8. `collect_worker_artifacts(...)`
+9. `terminate_worker(...)`
+
+Use opt-in MCP toolsets for extra surfaces:
+
+```bash
+agentpool mcp --toolsets default,stats,sessions,leases,worktrees
+```
+
+Startup prompts are provider UI, not task output. For Codex update prompts,
+send menu choice `2` to skip the update. For Codex directory trust prompts,
+send an empty submitted message to press the selected default only when trusting
+that directory is acceptable. Then observe again.
+
+When spawning Codex workers, leave `initial_prompt_mode` unset unless you have a
+reason to force it. The provider default uses the Codex CLI prompt argument path.
+Pass `reasoning_effort="high"` or another explicit value when the task needs a
+different Codex reasoning setting from the catalog default.
+
+## Safety Boundaries
+
+AgentPool does not choose providers, rank models, store credentials, scrape
+browser usage pages, merge, or push. Unknown usage is unknown, not available.

agentpool/docs/onboarding.md

@@ -0,0 +1,169 @@
+# AgentPool Onboarding
+
+AgentPool is a local control plane for explicitly selected coding-agent CLIs.
+It does not route automatically and it does not choose a provider for you.
+
+## Human CLI Setup
+
+1. Install the package in the repo environment:
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+```
+
+2. Initialize AgentPool and wire your MCP host:
+
+```bash
+agentpool init
+agentpool setup cursor
+agentpool config validate
+agentpool doctor --deep --privacy
+```
+
+3. Check configured workers and usage backends:
+
+```bash
+agentpool providers
+agentpool models
+agentpool setup all
+agentpool usage-summary --refresh
+```
+
+Usage probes support three live backends:
+
+- `native`: AgentPool's provider-specific probes.
+- `codexbar`: CodexBar CLI, if installed.
+- `ccusage`: optional Claude Code local-log telemetry.
+- `combined`: native first, CodexBar and ccusage as safe-source
+  fallback/enrichment where mapped.
+
+AgentPool only uses CodexBar's explicit non-browser sources by default. Browser
+cookie or web dashboard sources are not enabled implicitly because they can
+trigger macOS keychain prompts.
+
+4. Prove the control plane with a fake worker before using a real provider:
+
+```bash
+agentpool smoke --provider fake-question --repo .
+```
+
+Real-provider smoke tests require an explicit read-only opt-in:
+
+```bash
+agentpool smoke --provider codex-cli --repo /tmp/agentpool-smoke-repo --real-read-only
+```
+
+Real providers use configured smoke models by default. For Droid, AgentPool pins
+`glm-5.1` through a process-local settings file so a custom user default does
+not accidentally route to a local proxy:
+
+```bash
+agentpool smoke --provider droid-cli --model glm-5.1 --repo /tmp/agentpool-smoke-repo --real-read-only
+```
+
+Model defaults and harness quirks are catalog driven:
+
+```bash
+agentpool models --provider droid-cli
+agentpool models --provider codex-cli --json
+agentpool models --provider cursor-cli --json
+agentpool models validate --path ~/.agentpool/models.json
+agentpool config validate
+```
+
+Layer user JSON catalogs with `model_catalog_paths` in `~/.agentpool/config.yaml`;
+direct `providers.<id>.metadata.default_model` overrides still win. See
+`docs/model-catalog.md`.
+
+Compatibility note: the PRD calls the Factory coding product `factory-droid`,
+but AgentPool exposes it as `droid-cli` because the installed command is
+`droid`. Do not add a second inventory row unless a distinct Factory Droid
+harness appears.
+
+Cursor note: `cursor` is the MCP host target. `cursor-cli` is the worker
+provider for Cursor Agent CLI through the local `agent`/`cursor-agent` command.
+
+Use the lower-level lifecycle commands when you need to inspect or steer each
+step manually:
+
+```bash
+agentpool spawn --provider fake-question --repo . --task "Ask one question." --isolation read_only
+agentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 60 --json
+agentpool send <session-id> "Continue read-only."
+agentpool artifacts <session-id> --json
+agentpool transcript <session-id> --tail-lines 80 --json
+agentpool collect <session-id> --json
+agentpool terminate <session-id> --json
+```
+
+## MCP Host Setup
+
+Use this host config shape:
+
+```bash
+agentpool mcp-config --client generic
+```
+
+```json
+{
+  "mcpServers": {
+    "agentpool": {
+      "command": "agentpool",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+For verified install (deeplink or one-liner shell command):
+
+```bash
+agentpool setup cursor
+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
+```
+
+For raw config paste:
+
+```bash
+agentpool mcp-config --client claude-code --json
+agentpool mcp-config --client codex
+agentpool mcp-config --client cursor
+```
+
+See `docs/mcp-clients.md` for verified steps, manual fallbacks, and Claude
+Desktop paths.
+
+Agents may read these default resources at startup, or when they notice the
+resource is missing from their context:
+
+- `agentpool://onboarding`
+- `agentpool://skill.md`
+- `agentpool://sessions/{session_id}/transcript`
+- `agentpool://sessions/{session_id}/events`
+- `agentpool://artifacts/{session_id}`
+
+Do not inject full resources into every prompt if the agent already has them.
+The live state is in tools. Coding agents with shell access should usually use
+the CLI because it keeps transcripts and artifacts on disk until explicitly read.
+
+## Agent Operating Loop
+
+1. Read usage and model state (`agentpool usage-summary --json`, `agentpool models --json`, or the matching MCP tools).
+2. Pick the provider explicitly.
+3. Use `read_only` for exploration and choose `worktree` explicitly only when
+   AgentPool should create an isolated worktree.
+4. Spawn one narrow worker.
+5. Observe until question, approval, completion, error, or timeout.
+6. Send steering or interrupt deliberately.
+7. Use advisory file leases when multiple workers may touch the same files.
+8. Read bounded transcript pages only when the manifest/summary is not enough.
+9. Use paginated `sessions` / `list_sessions` reads for fleet metadata.
+10. Read the artifact manifest, then collect artifacts.
+11. Terminate sessions when done.
+
+AgentPool never merges, pushes, silently accepts overage, stores provider
+credentials, scrapes browser pages, or ranks providers.