agentcap-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentcap-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: API-key spend guard for unattended Codex CLI and Gemini CLI runs: hard per-run cap, kills the process at the limit.
 Project-URL: Homepage, https://agentcap.launchbench.studio
 Project-URL: Repository, https://github.com/Blitz00X/agentcap
@@ -186,8 +186,9 @@ test suite uses `httpx.MockTransport` and never calls the network.
 | Your own script | Any | Uses the OpenAI or Gemini SDK with base-URL environment variables. | No code changes: AgentCap sets `OPENAI_BASE_URL` and `GOOGLE_GEMINI_BASE_URL`. |
 
 Tested with a real Gemini API key on Gemini CLI 0.66 (spend metered from Google's
-usageMetadata, output clamped to the cap); Gemini CLI 0.58 and Codex CLI 0.163 are
-tested end-to-end against a local fake API only, not yet with real paid keys.
+usageMetadata, output clamped to the cap). Codex CLI 0.165 verified against a real
+OpenAI-compatible upstream (Ollama Cloud, gpt-oss:20b, cap stop with exit 3); not against
+OpenAI billing. Gemini CLI 0.58 and Codex CLI 0.163 are tested end-to-end against a local fake API only.
 
 **Platforms:** Linux and macOS. Windows: not yet (use WSL2).
 
@@ -333,8 +334,13 @@ the 0.x line.
 - The Free tier (per-run cap) needs no key and makes no network calls.
 
 After purchase you receive a licence key by email (via Polar). Activate it with
-`agentcap license activate <KEY>`; `agentcap license deactivate` removes it from
-this machine.
+`agentcap license activate <KEY>`. `agentcap license deactivate` asks the
+license server to release this activation (freeing the slot for another
+machine) and then removes the local license; if the server cannot be reached the
+local license is kept and the command exits 1 so you can retry. Use
+`agentcap license deactivate --local-only` to remove just the local file — the
+activation then still counts toward your 3 machines until you release it in the
+Polar customer portal.
 
 ## How it compares
 
@@ -348,6 +354,26 @@ this machine.
 
 Pick what matches your setup — these tools can also be combined.
 
+## FAQ
+
+**Does clamping output hurt quality?** Yes, it can: when the budget is tight
+AgentCap lowers max output tokens so the call fits; answers can be shorter or
+cut off. Use `--no-clamp` to refuse instead.
+
+**Does stopping roll back what the agent did?** No. At the cap AgentCap sends
+SIGTERM then SIGKILL; files or remote changes already made stay. Use git / small
+steps.
+
+**Is the ledger my provider bill?** No. It is a local estimate from published
+prices and reported usage; when usage is missing it charges the full reservation
+(conservative). Your provider invoice is authoritative.
+
+**Is the day cap shared across machines?** No. Hour/day caps are per machine
+(local SQLite ledger). A license covers 3 machines, each with its own budget.
+
+**What does one-time purchase include?** $12 once, all 0.x updates; not a
+promise of future major versions. 14-day refund window per purchase terms.
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Kutay Karahan.

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/README.md

@@ -156,8 +156,9 @@ test suite uses `httpx.MockTransport` and never calls the network.
 | Your own script | Any | Uses the OpenAI or Gemini SDK with base-URL environment variables. | No code changes: AgentCap sets `OPENAI_BASE_URL` and `GOOGLE_GEMINI_BASE_URL`. |
 
 Tested with a real Gemini API key on Gemini CLI 0.66 (spend metered from Google's
-usageMetadata, output clamped to the cap); Gemini CLI 0.58 and Codex CLI 0.163 are
-tested end-to-end against a local fake API only, not yet with real paid keys.
+usageMetadata, output clamped to the cap). Codex CLI 0.165 verified against a real
+OpenAI-compatible upstream (Ollama Cloud, gpt-oss:20b, cap stop with exit 3); not against
+OpenAI billing. Gemini CLI 0.58 and Codex CLI 0.163 are tested end-to-end against a local fake API only.
 
 **Platforms:** Linux and macOS. Windows: not yet (use WSL2).
 
@@ -303,8 +304,13 @@ the 0.x line.
 - The Free tier (per-run cap) needs no key and makes no network calls.
 
 After purchase you receive a licence key by email (via Polar). Activate it with
-`agentcap license activate <KEY>`; `agentcap license deactivate` removes it from
-this machine.
+`agentcap license activate <KEY>`. `agentcap license deactivate` asks the
+license server to release this activation (freeing the slot for another
+machine) and then removes the local license; if the server cannot be reached the
+local license is kept and the command exits 1 so you can retry. Use
+`agentcap license deactivate --local-only` to remove just the local file — the
+activation then still counts toward your 3 machines until you release it in the
+Polar customer portal.
 
 ## How it compares
 
@@ -318,6 +324,26 @@ this machine.
 
 Pick what matches your setup — these tools can also be combined.
 
+## FAQ
+
+**Does clamping output hurt quality?** Yes, it can: when the budget is tight
+AgentCap lowers max output tokens so the call fits; answers can be shorter or
+cut off. Use `--no-clamp` to refuse instead.
+
+**Does stopping roll back what the agent did?** No. At the cap AgentCap sends
+SIGTERM then SIGKILL; files or remote changes already made stay. Use git / small
+steps.
+
+**Is the ledger my provider bill?** No. It is a local estimate from published
+prices and reported usage; when usage is missing it charges the full reservation
+(conservative). Your provider invoice is authoritative.
+
+**Is the day cap shared across machines?** No. Hour/day caps are per machine
+(local SQLite ledger). A license covers 3 machines, each with its own budget.
+
+**What does one-time purchase include?** $12 once, all 0.x updates; not a
+promise of future major versions. 14-day refund window per purchase terms.
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Kutay Karahan.

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentcap-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "API-key spend guard for unattended Codex CLI and Gemini CLI runs: hard per-run cap, kills the process at the limit."
 readme = "README.md"
 requires-python = ">=3.11"

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/src/agentcap/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = ["__version__"]

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/src/agentcap/cli.py

@@ -18,6 +18,7 @@ from .alerts import dispatcher_from_env
 from .ledger import Caps, Ledger
 from .license import (
     LicenseManager,
+    LicenseNetworkError,
     features,
     status_from_environment,
 )
@@ -42,6 +43,45 @@ PRO_CAP_MESSAGE = (
     "command was not started. Run `agentcap license status`, then "
     '`agentcap license activate "YOUR_LICENSE_KEY"`.'
 )
+PRO_HINT = (
+    "hint: Pro is $12 one-time: https://agentcap.launchbench.studio/#pricing — "
+    'then `agentcap license activate "YOUR_LICENSE_KEY"`.'
+)
+PRO_ALERTS_MESSAGE = (
+    "agentcap: webhook/Telegram alerts require an active Pro license; "
+    "they are disabled for this run."
+)
+DEACTIVATE_NO_LICENSE = (
+    "agentcap: no active license on this machine; nothing to deactivate."
+)
+DEACTIVATE_LEGACY = (
+    "agentcap: local license removed. This activation was created by an older "
+    "version and could not be released on the server; manage activations in "
+    "the Polar customer portal."
+)
+DEACTIVATE_RELEASED = (
+    "agentcap: activation released on the license server and local license "
+    "removed. You can activate on another machine now."
+)
+DEACTIVATE_UNKNOWN = (
+    "agentcap: the license server no longer knows this activation (already "
+    "released?). Local license removed."
+)
+DEACTIVATE_LOCAL_ONLY = (
+    "agentcap: local license removed. The activation remains on the license "
+    "server; manage activations in the Polar customer portal."
+)
+
+
+def _deactivate_failure(reason: str) -> str:
+    return (
+        "agentcap: could not reach the license server to release this "
+        f"activation ({reason}). Local license kept; retry "
+        "`agentcap license deactivate` when online, or use `--local-only` to "
+        "just remove the local file."
+    )
+
+
 LICENSE_USAGE_MESSAGE = (
     'Usage: agentcap license activate "YOUR_LICENSE_KEY" '
     "(copy the key from your Polar purchase / customer portal)"
@@ -76,6 +116,11 @@ def _build_parser() -> argparse.ArgumentParser:
         help="status (default), features, activate <KEY>, or deactivate",
     )
     license_parser.add_argument("key", nargs="?", help="license key for 'activate'")
+    license_parser.add_argument(
+        "--local-only",
+        action="store_true",
+        help="deactivate: remove the local license without contacting the server",
+    )
 
     run = subparsers.add_parser(
         "run", help="run a command under a spend cap (use -- before the command)"
@@ -188,6 +233,81 @@ def _license_manager() -> LicenseManager:
     return LicenseManager()
 
 
+def _remove_local_license(manager: LicenseManager) -> bool:
+    try:
+        manager.clear()
+    except OSError as exc:
+        detail = exc.strerror or str(exc)
+        print(
+            "agentcap: could not remove the local license at "
+            f"{manager.path}: {detail}. Fix the file permission and try again.",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def _license_deactivate(manager: LicenseManager, *, local_only: bool = False) -> int:
+    cached = manager.cached_license()
+
+    if local_only:
+        # Remove whatever local file exists, even a stale or unreadable one.
+        if cached is None and not manager.path.exists():
+            print(DEACTIVATE_NO_LICENSE)
+            return 0
+        if not _remove_local_license(manager):
+            return 1
+        print(DEACTIVATE_LOCAL_ONLY)
+        return 0
+
+    if cached is None:
+        print(DEACTIVATE_NO_LICENSE)
+        return 0
+
+    if not cached.activation_id:
+        if not _remove_local_license(manager):
+            return 1
+        print(DEACTIVATE_LEGACY)
+        return 0
+
+    releaser = getattr(manager.validator, "deactivate", None)
+    if not callable(releaser):
+        print(
+            _deactivate_failure("server-side release is not supported"),
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        status_code = releaser(cached.key, cached.activation_id)
+    except Exception as exc:  # transport failures keep the local licence
+        if isinstance(exc, LicenseNetworkError):
+            reason = str(exc)
+        else:
+            reason = type(exc).__name__
+        # The key is a credential: never echo it, even from an error string.
+        if cached.key:
+            reason = reason.replace(cached.key, "<redacted>")
+        print(_deactivate_failure(reason), file=sys.stderr)
+        return 1
+
+    if status_code == 204:
+        if not _remove_local_license(manager):
+            return 1
+        print(DEACTIVATE_RELEASED)
+        return 0
+
+    if status_code == 404:
+        if not _remove_local_license(manager):
+            return 1
+        print(DEACTIVATE_UNKNOWN)
+        return 0
+
+    detail = "validation error" if status_code == 422 else f"HTTP {status_code}"
+    print(_deactivate_failure(detail), file=sys.stderr)
+    return 1
+
+
 def _license_persist_error(exc: OSError, path) -> str:
     detail = exc.strerror or str(exc)
     return (
@@ -218,13 +338,7 @@ def _license(args: argparse.Namespace) -> int:
         return 0 if status.valid else 1
 
     if args.action == "deactivate":
-        try:
-            manager.clear()
-        except OSError as exc:
-            print(_license_persist_error(exc, manager.path), file=sys.stderr)
-            return 1
-        print("license cache cleared")
-        return 0
+        return _license_deactivate(manager, local_only=bool(args.local_only))
 
     status = status_from_environment()
     if args.action == "features":
@@ -263,6 +377,25 @@ def _upstream_overrides() -> dict[str, str] | None:
     return {override.provider: override.url for override in overrides}
 
 
+def _warn_alerts_need_pro(active_features: set[str]) -> None:
+    """Explain why configured alert channels will stay silent on Free."""
+
+    webhook = bool(os.environ.get("AGENTCAP_WEBHOOK_URL", "").strip())
+    telegram = bool(
+        os.environ.get("AGENTCAP_TELEGRAM_BOT_TOKEN", "").strip()
+        and os.environ.get("AGENTCAP_TELEGRAM_CHAT_ID", "").strip()
+    )
+    if not (webhook or telegram):
+        return
+    gated = ("webhook_alerts" not in active_features) or (
+        "telegram_alerts" not in active_features
+    )
+    if not gated:
+        return
+    print(PRO_ALERTS_MESSAGE, file=sys.stderr)
+    print(PRO_HINT, file=sys.stderr)
+
+
 def _run(args: argparse.Namespace) -> int:
     if _windows_unsupported():
         print(WINDOWS_UNSUPPORTED, file=sys.stderr)
@@ -297,7 +430,9 @@ def _run(args: argparse.Namespace) -> int:
         or (day_cap is not None and "day_cap" not in active_features)
     ):
         print(PRO_CAP_MESSAGE, file=sys.stderr)
+        print(PRO_HINT, file=sys.stderr)
         return 2
+    _warn_alerts_need_pro(active_features)
 
     try:
         runner = Runner(
@@ -341,6 +476,7 @@ def _serve(args: argparse.Namespace) -> int:
         return 2
 
     active_features = set(features(status_from_environment().tier))
+    _warn_alerts_need_pro(active_features)
     run_id = f"serve-{int(time.time())}"
     alerts = dispatcher_from_env(features=active_features)
     config = ProxyConfig(

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/src/agentcap/license.py

@@ -48,6 +48,7 @@ _UNCONFIGURED_ORG_IDS = frozenset({"", "POLAR_ORG_ID_PLACEHOLDER"})
 
 VALIDATE_PATH = "/v1/customer-portal/license-keys/validate"
 ACTIVATE_PATH = "/v1/customer-portal/license-keys/activate"
+DEACTIVATE_PATH = "/v1/customer-portal/license-keys/deactivate"
 
 NOT_CONFIGURED_REASON = "license server not configured (AGENTCAP_POLAR_ORG_ID)"
 NOT_FOUND_REASON = "license key not found, revoked, disabled, or expired"
@@ -387,6 +388,28 @@ class PolarLicenseValidator:
             return self._reject(code, data, key), None
         raise LicenseNetworkError(f"license server returned HTTP {code}")
 
+    def deactivate(self, key: str, activation_id: str) -> int:
+        """Release one activation slot on the licence server.
+
+        Returns the HTTP status code: ``204`` means the activation was
+        released, ``404`` means the key/activation is unknown (already
+        released, or not belonging to this key), ``422`` is a validation
+        error.  Transport failures and 5xx responses raise
+        :class:`LicenseNetworkError` so the caller can keep the local licence.
+        """
+
+        org = self._configured_organization_id()
+        if org is None:
+            raise LicenseNetworkError(NOT_CONFIGURED_REASON)
+
+        payload: dict[str, object] = {
+            "key": key,
+            "organization_id": org,
+            "activation_id": activation_id,
+        }
+        response = self._post(DEACTIVATE_PATH, payload)
+        return response.status_code
+
 
 def status_from_environment() -> LicenseStatus:
     """Resolve the licence the way the CLI and runner do.
@@ -676,6 +699,14 @@ class LicenseManager:
             return None
         return cached.status
 
+    def cached_license(self) -> CachedLicense | None:
+        """The cached licence entry (key included) or ``None``.
+
+        Callers must never print the key: it is a credential.
+        """
+
+        return self._read()
+
     def clear(self) -> None:
         try:
             self.path.unlink()

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/src/agentcap/proxy.py

@@ -264,6 +264,9 @@ class _Proxy:
         self.observed_requests = 0
         #: Model requests refused before they reached the upstream.
         self.refused_requests = 0
+        #: Worst-case cost of the most recently refused request, so the runner
+        #: can suggest a cap when the very first request did not fit.
+        self.last_refused_reserved_usd: Decimal | None = None
         self.clamped_requests = 0
         self.killed = False
         self._thresholds_emitted: set[int] = set()
@@ -363,6 +366,9 @@ class _Proxy:
             "blocked_count": self.blocked_count,
             "observed_requests": self.observed_requests,
             "refused_requests": self.refused_requests,
+            "last_refused_reserved_usd": _optional_money(
+                self.last_refused_reserved_usd
+            ),
             "clamped_requests": self.clamped_requests,
             "killed": self.killed,
         }
@@ -540,6 +546,7 @@ class _Proxy:
         """Budget truly exhausted: reject and kill (at most once per run)."""
 
         self._count_blocked()
+        self.last_refused_reserved_usd = needed
         payload = {
             "scope": budget.scope,
             "cap_usd": str(budget.cap),
@@ -578,6 +585,7 @@ class _Proxy:
         """
 
         self._count_blocked()
+        self.last_refused_reserved_usd = needed
         payload = {
             "scope": budget.scope,
             "cap_usd": str(budget.cap),

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/src/agentcap/runner.py

@@ -20,13 +20,18 @@ import time
 import uuid
 from dataclasses import dataclass
 from datetime import datetime
-from decimal import Decimal
+from decimal import Decimal, ROUND_CEILING
 from typing import Any, Callable, Iterable, Mapping, Sequence, TextIO
 
 import httpx
 import uvicorn
 
-from .adapters import AdapterConflict, ensure_codex_routing_is_safe, prepare_child
+from .adapters import (
+    AdapterConflict,
+    detect_agent,
+    ensure_codex_routing_is_safe,
+    prepare_child,
+)
 from .alerts import AlertDispatcher, dispatcher_from_env
 from .ledger import Caps, Ledger
 from .license import features as license_features
@@ -55,10 +60,43 @@ ZERO_REQUEST_WARNING = (
     "Your agent may be calling the API directly "
     "(see README: Supported CLIs)."
 )
+ZERO_REQUEST_HINT = (
+    "hint: agentcap saw no API requests. The wrapped CLI may be using a "
+    "subscription/OAuth login (not metered) or a base URL agentcap does not "
+    "set. For Codex use an API key (OPENAI_API_KEY); for Gemini use "
+    "GEMINI_API_KEY. See README 'Supported'."
+)
+UNSUPPORTED_CLI_HINT = (
+    "hint: supported: codex, gemini, or any SDK script that honours "
+    "OPENAI_BASE_URL / GOOGLE_GEMINI_BASE_URL. Run `agentcap run --cap 1 -- "
+    "python your_script.py`."
+)
+FIRST_REQUEST_HINT = (
+    "hint: the first request alone needs about {reserved} (estimated, worst "
+    "case) but the cap is {cap}. Try --cap {suggested} (about 3x one request) "
+    "or lower max output."
+)
 YELLOW = "\033[33m"
 RESET = "\033[0m"
 
 
+def _hint_usd(value: Decimal) -> str:
+    """Short USD amount for hint lines: ``$0.01``, ``$0.0123``."""
+
+    text = f"{value:.4f}".rstrip("0")
+    whole, _, fraction = text.partition(".")
+    if len(fraction) < 2:
+        fraction = fraction.ljust(2, "0")
+    return f"${whole}.{fraction}"
+
+
+def _suggested_cap(reserved: Decimal) -> Decimal:
+    """About 3x one request, rounded up to cents, never below $0.05."""
+
+    tripled = (reserved * 3).quantize(Decimal("0.01"), rounding=ROUND_CEILING)
+    return max(Decimal("0.05"), tripled)
+
+
 @dataclass
 class RunSummary:
     """Numbers printed when a run ends."""
@@ -492,6 +530,8 @@ class Runner:
             self._print_summary(self.summary)
             if self.child is not None and self.summary.requests == 0:
                 self._warn_no_requests()
+                self._hint_no_requests()
+            self._hint_first_request_refused(self.summary)
         return exit_code
 
     def _build_summary(self, reason: str, exit_code: int) -> RunSummary:
@@ -538,6 +578,45 @@ class Runner:
         except Exception:
             pass
 
+    def _hint_no_requests(self) -> None:
+        """Actionable follow-up to the zero-request warning."""
+
+        self._print_hint(ZERO_REQUEST_HINT)
+        # An unknown CLI is the common cause: say what is supported as well.
+        if detect_agent(self.argv) is None:
+            self._print_hint(UNSUPPORTED_CLI_HINT)
+
+    def _hint_first_request_refused(self, summary: RunSummary) -> None:
+        """Explain an oversize first request and suggest a feasible cap."""
+
+        if summary.refused_requests < 1 or summary.spent_usd != 0:
+            return
+        proxy = self._proxy
+        reserved = (
+            getattr(proxy, "last_refused_reserved_usd", None)
+            if proxy is not None
+            else None
+        )
+        if reserved is None:
+            return
+        reserved = Decimal(str(reserved))
+        if reserved <= 0:
+            return
+        cap = "none" if summary.cap_usd is None else _hint_usd(summary.cap_usd)
+        self._print_hint(
+            FIRST_REQUEST_HINT.format(
+                reserved=_hint_usd(reserved),
+                cap=cap,
+                suggested=f"{_suggested_cap(reserved):.2f}",
+            )
+        )
+
+    def _print_hint(self, hint: str) -> None:
+        try:
+            print(hint, file=self.stderr, flush=True)
+        except Exception:
+            pass
+
 
 __all__ = [
     "Runner",

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/tests/test_cli.py

@@ -87,6 +87,41 @@ def test_free_tier_refuses_each_pro_cap_individually(fake_runner, capsys, flag):
     assert "require an active Pro license" in capsys.readouterr().err
 
 
+def test_free_tier_pro_refusal_includes_the_upgrade_hint(fake_runner, capsys):
+    assert cli.main(["run", "--hour-cap", "1", "--", "true"]) == 2
+    err = capsys.readouterr().err
+    assert (
+        "hint: Pro is $12 one-time: "
+        "https://agentcap.launchbench.studio/#pricing — then "
+        '`agentcap license activate "YOUR_LICENSE_KEY"`.'
+    ) in err
+
+
+def test_free_tier_alerts_are_gated_with_an_upgrade_hint(
+    fake_runner, monkeypatch, capsys
+):
+    monkeypatch.setenv("AGENTCAP_WEBHOOK_URL", "https://example.invalid/hook")
+
+    assert cli.main(["run", "--", "true"]) == 0
+    # The run still starts; only the Pro delivery channel is disabled.
+    assert len(fake_runner.instances) == 1
+    err = capsys.readouterr().err
+    assert "webhook/Telegram alerts require an active Pro license" in err
+    assert "hint: Pro is $12 one-time" in err
+
+
+def test_pro_alerts_do_not_print_the_upgrade_hint(
+    fake_runner, monkeypatch, tmp_path, capsys
+):
+    write_pro_cache(tmp_path / "license.json")
+    monkeypatch.setenv("AGENTCAP_WEBHOOK_URL", "https://example.invalid/hook")
+
+    assert cli.main(["run", "--", "true"]) == 0
+    err = capsys.readouterr().err
+    assert "require an active Pro license" not in err
+    assert "hint: Pro is $12 one-time" not in err
+
+
 def test_pro_license_enables_hour_and_day_caps(fake_runner, tmp_path, capsys):
     write_pro_cache(tmp_path / "license.json")
     assert cli.main(
@@ -226,15 +261,20 @@ def test_license_status_reads_cached_polar_license(monkeypatch, tmp_path, capsys
 
 def test_license_deactivate_clears_local_cache(monkeypatch, tmp_path, capsys):
     path = tmp_path / "license.json"
-    write_pro_cache(path)
+    write_pro_cache(path)  # older cache entry: no activation_id
     monkeypatch.setenv("AGENTCAP_LICENSE_FILE", str(path))
 
     assert cli.main(["license", "deactivate"]) == 0
     assert not path.exists()
-    assert capsys.readouterr().out.strip() == "license cache cleared"
+    out = capsys.readouterr().out.strip()
+    assert "local license removed" in out
+    assert "older version" in out
+    assert "Polar customer portal" in out
+    assert "polar-key" not in out
 
     # Idempotent: no cache is not an error.
     assert cli.main(["license", "deactivate"]) == 0
+    assert "nothing to deactivate" in capsys.readouterr().out
 
 
 def test_license_activate_without_key_fails(monkeypatch, tmp_path, capsys):
@@ -319,6 +359,7 @@ def test_license_deactivate_clear_error_is_reported_without_traceback(
     monkeypatch, tmp_path, capsys
 ):
     path = tmp_path / "license.json"
+    write_pro_cache(path)  # legacy entry: removal is local-only
     monkeypatch.setenv("AGENTCAP_LICENSE_FILE", str(path))
 
     def fail_clear(self):
@@ -328,12 +369,236 @@ def test_license_deactivate_clear_error_is_reported_without_traceback(
 
     assert cli.main(["license", "deactivate"]) == 1
     captured = capsys.readouterr()
-    assert "license validated, but could not save activation" in captured.err
+    assert "could not remove the local license" in captured.err
     assert str(path) in captured.err
     assert "Permission denied" in captured.err
     assert "Traceback" not in captured.err
 
 
+@pytest.fixture()
+def deactivation(monkeypatch, tmp_path):
+    """A fake Polar validator for `license deactivate` + the cache path."""
+
+    state: dict = {"status": 204, "error": None, "calls": []}
+
+    class StubPolar:
+        persist = True
+
+        def __init__(self, *args, **kwargs) -> None:
+            pass
+
+        def validate(self, key, activation_id=None):
+            raise AssertionError("deactivate must not re-validate the key")
+
+        def activate(self, key):
+            raise AssertionError("deactivate must not activate")
+
+        def deactivate(self, key, activation_id):
+            state["calls"].append((key, activation_id))
+            if state["error"] is not None:
+                raise state["error"]
+            return state["status"]
+
+    monkeypatch.setattr(license_module, "PolarLicenseValidator", StubPolar)
+    path = tmp_path / "license.json"
+    monkeypatch.setenv("AGENTCAP_LICENSE_FILE", str(path))
+    return state, path
+
+
+def _write_cache_with_activation(path, activation_id="act_cached", key="polar-key"):
+    path.write_text(
+        json.dumps(
+            {
+                "key": key,
+                "tier": "pro",
+                "valid": True,
+                "reason": "license valid",
+                "checked_at": time.time(),
+                "source": "polar",
+                "activation_id": activation_id,
+            }
+        ),
+        encoding="utf-8",
+    )
+    return path
+
+
+def test_license_deactivate_without_local_license_is_a_noop(deactivation, capsys):
+    state, path = deactivation
+    assert cli.main(["license", "deactivate"]) == 0
+    captured = capsys.readouterr()
+    assert captured.out.strip() == (
+        "agentcap: no active license on this machine; nothing to deactivate."
+    )
+    assert state["calls"] == []
+    assert not path.exists()
+
+
+def test_license_deactivate_legacy_cache_removes_without_server_call(
+    deactivation, capsys
+):
+    state, path = deactivation
+    _write_cache_with_activation(path, activation_id=None)
+
+    assert cli.main(["license", "deactivate"]) == 0
+    captured = capsys.readouterr()
+    assert not path.exists()
+    assert state["calls"] == []
+    assert captured.out.strip() == (
+        "agentcap: local license removed. This activation was created by an "
+        "older version and could not be released on the server; manage "
+        "activations in the Polar customer portal."
+    )
+    assert "polar-key" not in captured.out + captured.err
+
+
+def test_license_deactivate_released_on_server_removes_local_file(
+    deactivation, capsys
+):
+    state, path = deactivation
+    _write_cache_with_activation(path, activation_id="act_cached")
+
+    assert cli.main(["license", "deactivate"]) == 0
+    captured = capsys.readouterr()
+    assert not path.exists()
+    assert state["calls"] == [("polar-key", "act_cached")]
+    assert captured.out.strip() == (
+        "agentcap: activation released on the license server and local license "
+        "removed. You can activate on another machine now."
+    )
+    assert "polar-key" not in captured.out + captured.err
+
+
+def test_license_deactivate_unknown_activation_still_removes_local_file(
+    deactivation, capsys
+):
+    state, path = deactivation
+    state["status"] = 404
+    _write_cache_with_activation(path, activation_id="act_gone")
+
+    assert cli.main(["license", "deactivate"]) == 0
+    captured = capsys.readouterr()
+    assert not path.exists()
+    assert state["calls"] == [("polar-key", "act_gone")]
+    assert captured.out.strip() == (
+        "agentcap: the license server no longer knows this activation "
+        "(already released?). Local license removed."
+    )
+    assert "polar-key" not in captured.out + captured.err
+
+
+@pytest.mark.parametrize(
+    ("status", "reason"),
+    [(422, "validation error"), (429, "HTTP 429"), (400, "HTTP 400")],
+)
+def test_license_deactivate_rejected_keeps_local_license(
+    deactivation, capsys, status, reason
+):
+    state, path = deactivation
+    state["status"] = status
+    _write_cache_with_activation(path, activation_id="act_cached")
+
+    assert cli.main(["license", "deactivate"]) == 1
+    captured = capsys.readouterr()
+    assert path.exists()
+    assert state["calls"] == [("polar-key", "act_cached")]
+    assert captured.err.startswith("agentcap: could not reach the license server")
+    assert f"({reason})" in captured.err
+    assert "Local license kept" in captured.err
+    assert "`agentcap license deactivate`" in captured.err
+    assert "`--local-only`" in captured.err
+    assert "polar-key" not in captured.out + captured.err
+
+
+@pytest.mark.parametrize(
+    "error",
+    [
+        LicenseNetworkError("license server unreachable (ConnectError)"),
+        LicenseNetworkError("license server error (HTTP 503)"),
+        LicenseNetworkError("license server request timed out"),
+    ],
+)
+def test_license_deactivate_network_failure_keeps_local_license(
+    deactivation, capsys, error
+):
+    state, path = deactivation
+    state["error"] = error
+    _write_cache_with_activation(path, activation_id="act_cached")
+
+    assert cli.main(["license", "deactivate"]) == 1
+    captured = capsys.readouterr()
+    assert path.exists()
+    assert f"({error})" in captured.err
+    assert "could not reach the license server to release this activation" in (
+        captured.err
+    )
+    assert "polar-key" not in captured.out + captured.err
+
+
+def test_license_deactivate_unexpected_validator_error_is_reported(
+    deactivation, capsys
+):
+    state, path = deactivation
+    state["error"] = RuntimeError("boom")
+    _write_cache_with_activation(path, activation_id="act_cached")
+
+    assert cli.main(["license", "deactivate"]) == 1
+    captured = capsys.readouterr()
+    assert path.exists()
+    assert "(RuntimeError)" in captured.err
+    assert "Traceback" not in captured.err
+
+
+def test_license_deactivate_local_only_skips_server(deactivation, capsys):
+    state, path = deactivation
+    _write_cache_with_activation(path, activation_id="act_cached")
+
+    assert cli.main(["license", "deactivate", "--local-only"]) == 0
+    captured = capsys.readouterr()
+    assert not path.exists()
+    assert state["calls"] == []
+    assert "local license removed" in captured.out
+    assert "remains on the license server" in captured.out
+    assert "polar-key" not in captured.out + captured.err
+
+
+def test_license_deactivate_local_only_removes_legacy_cache_without_warning(
+    deactivation, capsys
+):
+    state, path = deactivation
+    _write_cache_with_activation(path, activation_id=None)
+
+    assert cli.main(["license", "deactivate", "--local-only"]) == 0
+    captured = capsys.readouterr()
+    assert not path.exists()
+    assert state["calls"] == []
+    assert "remains on the license server" in captured.out
+
+
+def test_license_deactivate_local_only_without_a_file_is_a_noop(deactivation, capsys):
+    state, path = deactivation
+
+    assert cli.main(["license", "deactivate", "--local-only"]) == 0
+    captured = capsys.readouterr()
+    assert captured.out.strip() == (
+        "agentcap: no active license on this machine; nothing to deactivate."
+    )
+    assert state["calls"] == []
+
+
+def test_license_deactivate_local_only_removes_an_unreadable_cache(
+    deactivation, capsys
+):
+    state, path = deactivation
+    path.write_text("{not json", encoding="utf-8")
+
+    assert cli.main(["license", "deactivate", "--local-only"]) == 0
+    captured = capsys.readouterr()
+    assert not path.exists()
+    assert state["calls"] == []
+    assert "remains on the license server" in captured.out
+
+
 @pytest.mark.parametrize("platform_name", ["nt"])
 def test_run_refuses_windows_before_starting(
     monkeypatch, fake_runner, capsys, platform_name

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/tests/test_license.py

@@ -16,6 +16,7 @@ import pytest
 from agentcap import __version__
 from agentcap.license import (
     ACTIVATE_PATH,
+    DEACTIVATE_PATH,
     NOT_CONFIGURED_REASON,
     NOT_FOUND_REASON,
     POLAR_API_BASE,
@@ -76,10 +77,11 @@ def _offline_guard(monkeypatch):
 class PolarStub:
     """Routes customer-portal calls to queued mocked responses."""
 
-    def __init__(self, *, validate=None, activate=None) -> None:
+    def __init__(self, *, validate=None, activate=None, deactivate=None) -> None:
         self.requests: list[dict[str, object]] = []
         self._validate = validate
         self._activate = activate
+        self._deactivate = deactivate
         self.transport = httpx.MockTransport(self._handle)
 
     def _handle(self, request: httpx.Request) -> httpx.Response:
@@ -92,7 +94,11 @@ class PolarStub:
             }
         )
         name = request.url.path.rsplit("/", 1)[-1]
-        responder = self._validate if name == "validate" else self._activate
+        responder = {
+            "validate": self._validate,
+            "activate": self._activate,
+            "deactivate": self._deactivate,
+        }.get(name)
         if responder is None:
             raise AssertionError(f"unexpected request to {request.url.path}")
         if callable(responder):
@@ -585,6 +591,64 @@ def test_activate_rejection_keeps_cache_for_a_different_key(tmp_path):
     assert manager.check().valid is True
 
 
+# -------------------------------------------------------------- deactivation
+def test_deactivate_releases_activation_with_key_and_org():
+    clock = FakeClock()
+    stub = PolarStub(deactivate=httpx.Response(204))
+    validator = make_validator(stub, clock)
+
+    assert validator.deactivate(KEY, "act_123") == 204
+    assert stub.paths == [DEACTIVATE_PATH]
+    assert DEACTIVATE_PATH == "/v1/customer-portal/license-keys/deactivate"
+    assert stub.payloads == [
+        {"key": KEY, "organization_id": ORG, "activation_id": "act_123"}
+    ]
+
+
+def test_deactivate_unknown_activation_returns_404():
+    clock = FakeClock()
+    stub = PolarStub(deactivate=httpx.Response(404, json={"detail": "Not found"}))
+    assert make_validator(stub, clock).deactivate(KEY, "act_gone") == 404
+    assert stub.paths == [DEACTIVATE_PATH]
+
+
+def test_deactivate_validation_error_returns_422():
+    clock = FakeClock()
+    stub = PolarStub(
+        deactivate=httpx.Response(422, json={"detail": "activation_id is required"})
+    )
+    assert make_validator(stub, clock).deactivate(KEY, "act_bad") == 422
+
+
+def test_deactivate_network_error_raises_without_echoing_key():
+    clock = FakeClock()
+    stub = PolarStub(deactivate=raise_connect)
+    with pytest.raises(LicenseNetworkError) as excinfo:
+        make_validator(stub, clock).deactivate(KEY, "act_123")
+    assert KEY not in str(excinfo.value)
+
+
+def test_deactivate_5xx_raises_network_error():
+    clock = FakeClock()
+    stub = PolarStub(deactivate=httpx.Response(503, json={"detail": "unavailable"}))
+    with pytest.raises(LicenseNetworkError):
+        make_validator(stub, clock).deactivate(KEY, "act_123")
+    assert stub.paths == [DEACTIVATE_PATH]
+
+
+def test_deactivate_without_org_makes_no_request(monkeypatch):
+    monkeypatch.setenv("AGENTCAP_POLAR_ORG_ID", "POLAR_ORG_ID_PLACEHOLDER")
+    stub = PolarStub()  # any request would raise
+    validator = PolarLicenseValidator(
+        base_url=BASE,
+        client=httpx.Client(transport=stub.transport),
+        clock=FakeClock(),
+    )
+    with pytest.raises(LicenseNetworkError):
+        validator.deactivate(KEY, "act_123")
+    assert stub.requests == []
+
+
 # --------------------------------------------------------------------- cache
 def test_cache_is_reused_within_seven_days_without_http(tmp_path):
     clock = FakeClock()

{agentcap_cli-0.1.3 → agentcap_cli-0.1.4}/tests/test_runner.py

@@ -279,8 +279,11 @@ def test_zero_request_warning_is_yellow_on_a_tty(tmp_path):
     stderr = _TtyStringIO()
     runner, _ = _runner(tmp_path, [sys.executable, "-c", "pass"], err=stderr)
     assert runner.run() == 0
-    assert "\033[33m" in stderr.getvalue()
-    assert stderr.getvalue().rstrip().endswith("\033[0m")
+    output = stderr.getvalue()
+    assert "\033[33m" in output
+    assert "\033[0m" in output
+    # The actionable hint follows the coloured warning, uncoloured.
+    assert output.rstrip().splitlines()[-1].startswith("hint: ")
 
 
 def test_no_zero_request_warning_when_requests_were_metered(tmp_path):
@@ -426,3 +429,121 @@ def test_terminate_kills_grandchild_after_leader_already_exited(tmp_path):
     while time.monotonic() < deadline and _process_alive(grandchild):
         time.sleep(0.02)
     assert not _process_alive(grandchild)
+
+
+# ------------------------------------------------------------ actionable hints
+def _fake_cli(tmp_path: Path, name: str = "codex") -> Path:
+    path = tmp_path / name
+    path.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+    path.chmod(0o755)
+    return path
+
+
+def test_zero_request_hint_for_supported_cli(tmp_path):
+    runner, stderr = _runner(tmp_path, [str(_fake_cli(tmp_path))])
+    assert runner.run() == 0
+    output = stderr.getvalue()
+    assert "hint: agentcap saw no API requests." in output
+    assert "OPENAI_API_KEY" in output
+    assert "GEMINI_API_KEY" in output
+    assert "README 'Supported'" in output
+    assert "hint: supported: codex, gemini" not in output
+
+
+def test_zero_request_hint_for_unknown_cli_names_supported_tools(tmp_path):
+    runner, stderr = _runner(tmp_path, [sys.executable, "-c", "pass"])
+    assert runner.run() == 0
+    output = stderr.getvalue()
+    assert "hint: agentcap saw no API requests." in output
+    assert "hint: supported: codex, gemini" in output
+    assert "OPENAI_BASE_URL / GOOGLE_GEMINI_BASE_URL" in output
+    assert "agentcap run --cap 1 -- python your_script.py" in output
+    # The no-traffic hint comes first, then the supported-CLI hint.
+    assert output.index("hint: agentcap saw no API requests.") < output.index(
+        "hint: supported:"
+    )
+
+
+def test_unknown_cli_hint_is_not_printed_when_traffic_was_metered(tmp_path):
+    child = [
+        sys.executable,
+        "-c",
+        (
+            "import os, httpx\n"
+            "httpx.post(os.environ['OPENAI_BASE_URL'] + '/chat/completions',\n"
+            "           json={'model': 'gpt-4o-mini',\n"
+            "                 'messages': [{'role': 'user', 'content': 'hi'}]},\n"
+            "           timeout=5)\n"
+        ),
+    ]
+    runner, stderr = _runner(tmp_path, child, cap="1")
+    assert runner.run() == 0
+    output = stderr.getvalue()
+    assert "hint: supported:" not in output
+    assert "hint: agentcap saw no API requests." not in output
+
+
+def test_first_request_refusal_hint_suggests_three_times_the_reservation(tmp_path):
+    child = [
+        sys.executable,
+        "-c",
+        (
+            "import os, sys, httpx\n"
+            "httpx.post(os.environ['OPENAI_BASE_URL'] + '/chat/completions',\n"
+            "           json={'model': 'gpt-4o-mini',\n"
+            "                 'messages': [{'role': 'user', 'content': 'hi'}],\n"
+            "                 'max_completion_tokens': 100000},\n"
+            "           timeout=5)\n"
+            "sys.exit(0)\n"
+        ),
+    ]
+    runner, stderr = _runner(tmp_path, child, cap="0.01", clamp_output=False)
+    assert runner.run() == 0
+    summary = runner.summary
+    assert summary is not None
+    assert summary.spent_usd == 0
+    assert summary.refused_requests == 1
+    reserved = runner._proxy.last_refused_reserved_usd
+    assert reserved is not None and reserved > 0
+    from agentcap.runner import _hint_usd, _suggested_cap
+
+    output = stderr.getvalue()
+    assert (
+        f"hint: the first request alone needs about {_hint_usd(reserved)}"
+        in output
+    )
+    assert "but the cap is $0.01." in output
+    assert (
+        f"Try --cap {_suggested_cap(reserved):.2f} (about 3x one request)"
+        in output
+    )
+    assert "or lower max output." in output
+
+
+def test_no_first_request_hint_when_requests_were_served(tmp_path):
+    child = [
+        sys.executable,
+        "-c",
+        (
+            "import os, httpx\n"
+            "httpx.post(os.environ['OPENAI_BASE_URL'] + '/chat/completions',\n"
+            "           json={'model': 'gpt-4o-mini',\n"
+            "                 'messages': [{'role': 'user', 'content': 'hi'}]},\n"
+            "           timeout=5)\n"
+        ),
+    ]
+    runner, stderr = _runner(tmp_path, child, cap="1")
+    assert runner.run() == 0
+    assert "hint: the first request alone" not in stderr.getvalue()
+
+
+def test_suggested_cap_rounds_up_and_has_a_floor():
+    from agentcap.runner import _hint_usd, _suggested_cap
+
+    assert _suggested_cap(Decimal("0.001")) == Decimal("0.05")
+    assert _suggested_cap(Decimal("0.0123")) == Decimal("0.05")
+    assert _suggested_cap(Decimal("0.02")) == Decimal("0.06")
+    assert _suggested_cap(Decimal("0.06")) == Decimal("0.18")
+    assert _hint_usd(Decimal("0.01")) == "$0.01"
+    assert _hint_usd(Decimal("0.0123")) == "$0.0123"
+    assert _hint_usd(Decimal("0")) == "$0.00"