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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentcap-cli
-Version: 0.1.2
+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
@@ -71,6 +71,8 @@ pipx install agentcap-cli
 pip install agentcap-cli
 ```
 
+No pipx? macOS: `brew install pipx && pipx ensurepath`; Linux: `python3 -m pip install --user pipx && python3 -m pipx ensurepath`.
+
 From a checkout:
 
 ```bash
@@ -184,8 +186,11 @@ 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).
 
 ## How it works
 
@@ -329,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
 
@@ -344,10 +354,32 @@ 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.
 
+After purchase, copy your license key from your Polar order (purchase email / Polar customer portal), then run `agentcap license activate "YOUR_LICENSE_KEY"` and check with `agentcap license status` (expect `tier: pro`).
+
 The Pro licence key is separate from the source licence. How it is checked:
 
 - On activation the key is validated against Polar's public licence API

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

@@ -41,6 +41,8 @@ pipx install agentcap-cli
 pip install agentcap-cli
 ```
 
+No pipx? macOS: `brew install pipx && pipx ensurepath`; Linux: `python3 -m pip install --user pipx && python3 -m pipx ensurepath`.
+
 From a checkout:
 
 ```bash
@@ -154,8 +156,11 @@ 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).
 
 ## How it works
 
@@ -299,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
 
@@ -314,10 +324,32 @@ 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.
 
+After purchase, copy your license key from your Polar order (purchase email / Polar customer portal), then run `agentcap license activate "YOUR_LICENSE_KEY"` and check with `agentcap license status` (expect `tier: pro`).
+
 The Pro licence key is separate from the source licence. How it is checked:
 
 - On activation the key is validated against Polar's public licence API

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentcap-cli"
-version = "0.1.2"
+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.2 → agentcap_cli-0.1.4}/src/agentcap/__init__.py

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

{agentcap_cli-0.1.2 → 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,
 )
@@ -33,11 +34,72 @@ from .upstreams import UpstreamConfigError, resolve_upstreams
 
 DEFAULT_SERVE_PORT = 8787
 
+WINDOWS_UNSUPPORTED = (
+    "agentcap: Windows is not supported yet (process-group stop is POSIX-only). "
+    "Use WSL2, macOS or Linux."
+)
+PRO_CAP_MESSAGE = (
+    "agentcap: --hour-cap/--day-cap require an active Pro license; "
+    "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)"
+)
+LICENSE_INVALID_MESSAGE = (
+    "License key not found or no longer valid. Check the copied key; "
+    "if it still fails, email kutaykarahan6@gmail.com."
+)
+
+
+def _windows_unsupported() -> bool:
+    return os.name == "nt" or sys.platform.startswith("win")
+
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="agentcap",
-        description="Local, hard USD cap for AI agent runs.",
+        description="Local USD spend cap for AI agent runs.",
     )
     parser.add_argument("--version", action="version", version=f"agentcap {__version__}")
     subparsers = parser.add_subparsers(dest="subcommand")
@@ -54,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)"
@@ -166,21 +233,112 @@ 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 (
+        "agentcap: license validated, but could not save activation to "
+        f"{path}: {detail}. Check write permission and free disk space."
+    )
+
+
 def _license(args: argparse.Namespace) -> int:
+    manager = _license_manager()
     if args.action == "activate":
         if not args.key:
-            print("agentcap: license activate requires a key", file=sys.stderr)
+            print(LICENSE_USAGE_MESSAGE, file=sys.stderr)
             return 2
-        status = _license_manager().activate(args.key)
+        try:
+            status = manager.activate(args.key)
+        except OSError as exc:
+            print(_license_persist_error(exc, manager.path), file=sys.stderr)
+            return 1
         print(f"tier: {status.tier}")
         print(f"valid: {status.valid}")
         print(f"reason: {status.reason}")
+        if (
+            not status.valid
+            and "could not reach the license server" not in status.reason
+        ):
+            print(LICENSE_INVALID_MESSAGE, file=sys.stderr)
         return 0 if status.valid else 1
 
     if args.action == "deactivate":
-        _license_manager().clear()
-        print("license cache cleared")
-        return 0
+        return _license_deactivate(manager, local_only=bool(args.local_only))
 
     status = status_from_environment()
     if args.action == "features":
@@ -189,6 +347,7 @@ def _license(args: argparse.Namespace) -> int:
         print(f"tier: {status.tier}")
         print(f"valid: {status.valid}")
         print(f"reason: {status.reason}")
+        print(f"cache path: {manager.path}")
     return 0
 
 
@@ -218,7 +377,29 @@ 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)
+        return 2
     argv = list(args.argv)
     if argv and argv[0] == "--":
         argv = argv[1:]
@@ -244,18 +425,14 @@ def _run(args: argparse.Namespace) -> int:
         return 2
 
     active_features = set(features(status_from_environment().tier))
-    if hour_cap is not None and "hour_cap" not in active_features:
-        print(
-            "agentcap: --hour-cap requires AgentCap Pro; ignoring it on the free tier.",
-            file=sys.stderr,
-        )
-        hour_cap = None
-    if day_cap is not None and "day_cap" not in active_features:
-        print(
-            "agentcap: --day-cap requires AgentCap Pro; ignoring it on the free tier.",
-            file=sys.stderr,
-        )
-        day_cap = None
+    if (
+        (hour_cap is not None and "hour_cap" not in active_features)
+        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(
@@ -299,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(
@@ -327,6 +505,9 @@ def _serve(args: argparse.Namespace) -> int:
 
 # ------------------------------------------------------------------------ demo
 def _demo(_args: argparse.Namespace) -> int:
+    if _windows_unsupported():
+        print(WINDOWS_UNSUPPORTED, file=sys.stderr)
+        return 2
     from .demo import run_demo
 
     return run_demo()

{agentcap_cli-0.1.2 → 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.
@@ -569,16 +592,23 @@ class LicenseManager:
 
         if status.valid:
             if self.persists:
-                self._write(
-                    effective_key,
-                    status,
-                    now,
-                    activation_id,
-                    last_attempt_at=now,
-                )
+                try:
+                    self._write(
+                        effective_key,
+                        status,
+                        now,
+                        activation_id,
+                        last_attempt_at=now,
+                    )
+                except OSError:
+                    # A read-only cache must not break a validated run.
+                    pass
         elif same_key is not None and self.persists:
             # Definitive rejection: make sure a stale Pro cache cannot survive.
-            self.clear()
+            try:
+                self.clear()
+            except OSError:
+                pass
         return status
 
     def _offline(
@@ -669,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()