agentpool-cli 0.1.0__py3-none-any.whl

agentpool/usage/provider_parsers.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+from agentpool.models import CapacitySnapshot, Confidence, UsageStatus, UsageWindow, UsageWindowKind
+
+
+def parse_codex_status(provider_id: str, text: str) -> CapacitySnapshot | None:
+    windows: list[UsageWindow] = []
+    for name, percent, reset in re.findall(
+        r"(?P<name>5h|Weekly)\s+limit:\s+\[[^\]]+\]\s+(?P<percent>\d+(?:\.\d+)?)%\s+left\s+\(resets\s+(?P<reset>[^)]+)\)",
+        text,
+        re.I,
+    ):
+        windows.append(
+            UsageWindow(
+                name=name.lower(),
+                kind=UsageWindowKind.FIVE_HOUR if name.lower() == "5h" else UsageWindowKind.WEEKLY,
+                remaining_percent=float(percent),
+                used_percent=100.0 - float(percent),
+                confidence=Confidence.LOCAL_CLI,
+                raw_text=f"{name} limit resets {reset}",
+            )
+        )
+    footer = re.search(
+        r"\b5h\s+(?P<hour>\d+(?:\.\d+)?)%\s+.*?\bweekly\s+(?P<weekly>\d+(?:\.\d+)?)%",
+        text,
+        re.I | re.S,
+    )
+    if footer and not windows:
+        windows.extend(
+            [
+                UsageWindow(
+                    name="5h",
+                    kind=UsageWindowKind.FIVE_HOUR,
+                    remaining_percent=float(footer.group("hour")),
+                    used_percent=100.0 - float(footer.group("hour")),
+                    confidence=Confidence.LOCAL_CLI,
+                    raw_text=footer.group(0),
+                ),
+                UsageWindow(
+                    name="weekly",
+                    kind=UsageWindowKind.WEEKLY,
+                    remaining_percent=float(footer.group("weekly")),
+                    used_percent=100.0 - float(footer.group("weekly")),
+                    confidence=Confidence.LOCAL_CLI,
+                    raw_text=footer.group(0),
+                ),
+            ]
+        )
+    if not windows:
+        return None
+    status = _status_from_remaining(min(w.remaining_percent or 100.0 for w in windows))
+    return CapacitySnapshot(provider_id=provider_id, status=status, confidence=Confidence.LOCAL_CLI, windows=windows)
+
+
+
+def parse_claude_usage(provider_id: str, text: str) -> CapacitySnapshot | None:
+    clean = _strip_ansi(text)
+    if re.search(r"failed to load usage|token expired|not authenticated|login required", clean, re.I):
+        return CapacitySnapshot(
+            provider_id=provider_id,
+            status=UsageStatus.UNAUTHENTICATED,
+            confidence=Confidence.LOCAL_CLI,
+            warnings=["Claude CLI reported that usage could not be loaded."],
+            raw={"source": "claude_cli_usage_error"},
+        )
+    windows: list[UsageWindow] = []
+    for label, name in (
+        ("Current session", "session"),
+        ("Current week (all models)", "weekly"),
+        ("Current week (Opus)", "weekly_opus"),
+        ("Current week (Sonnet only)", "weekly_sonnet"),
+        ("Current week (Sonnet)", "weekly_sonnet"),
+        ("Current week", "weekly"),
+    ):
+        window = _extract_labeled_percent(clean, label, name)
+        if window and all(existing.name != window.name for existing in windows):
+            windows.append(window)
+    if not windows:
+        return None
+    credits_remaining = None
+    extra = re.search(
+        r"Extra usage(?P<context>.{0,260}?\$(?P<spent>\d+(?:\.\d+)?)\s*/\s*\$(?P<limit>\d+(?:\.\d+)?)\s+spent)",
+        clean,
+        re.I | re.S,
+    )
+    if extra:
+        spent = float(extra.group("spent"))
+        limit = float(extra.group("limit"))
+        remaining = max(0.0, limit - spent)
+        credits_remaining = round(remaining, 2)
+        used_percent = (spent / limit) * 100 if limit > 0 else 100.0
+        windows.append(
+            UsageWindow(
+                name="extra_usage",
+                kind=UsageWindowKind.ON_DEMAND,
+                used_percent=max(0.0, min(100.0, used_percent)),
+                remaining_percent=max(0.0, min(100.0, 100.0 - used_percent)),
+                used_units=spent,
+                remaining_units=credits_remaining,
+                confidence=Confidence.LOCAL_CLI,
+                raw_text=extra.group("context").strip(),
+            )
+        )
+    status = _status_from_remaining(min(w.remaining_percent or 100.0 for w in windows))
+    return CapacitySnapshot(
+        provider_id=provider_id,
+        status=status,
+        confidence=Confidence.LOCAL_CLI,
+        windows=windows,
+        credits_remaining=credits_remaining,
+    )
+
+
+def parse_devin_usage(provider_id: str, text: str) -> CapacitySnapshot | None:
+    match = re.search(r"Quota used:\s+(?P<used>\d+(?:\.\d+)?)%\s+\(remaining:\s+(?P<remaining>\d+(?:\.\d+)?)%\)", text, re.I)
+    if not match:
+        banner = re.search(r"\b(?P<remaining>\d+(?:\.\d+)?)%\s+remaining\s+\(resets\s+in\s+(?P<reset>[^)]+)\)", text, re.I)
+        if not banner:
+            return None
+        remaining = float(banner.group("remaining"))
+        used = 100.0 - remaining
+        raw = banner.group(0)
+    else:
+        used = float(match.group("used"))
+        remaining = float(match.group("remaining"))
+        raw = match.group(0)
+    credits = None
+    credits_match = re.search(r"Extra usage balance:\s+\$(?P<credits>\d+(?:\.\d+)?)", text, re.I)
+    if credits_match:
+        credits = float(credits_match.group("credits"))
+    reset_at = _parse_devin_reset(text)
+    return CapacitySnapshot(
+        provider_id=provider_id,
+        status=_status_from_remaining(remaining),
+        confidence=Confidence.LOCAL_CLI,
+        credits_remaining=credits,
+        warnings=["Devin CLI /usage exposes the weekly included quota; daily quota requires the plan-status API."],
+        windows=[
+            UsageWindow(
+                name="weekly",
+                kind=UsageWindowKind.WEEKLY,
+                status="weekly",
+                used_percent=used,
+                remaining_percent=remaining,
+                reset_at=reset_at,
+                confidence=Confidence.LOCAL_CLI,
+                raw_text=raw,
+            )
+        ],
+    )
+
+
+def parse_droid_status(provider_id: str, text: str) -> CapacitySnapshot | None:
+    if "Credit Usage (Current Session)" not in text and "Session Token Usage" not in text:
+        return None
+    raw: dict[str, float] = {}
+    for key, value in re.findall(r"(Input|Output|Cache Creation|Cache Read):\s+([\d.]+)\s+(?:credits|tokens)", text, re.I):
+        raw[key.lower().replace(" ", "_")] = float(value)
+    return CapacitySnapshot(
+        provider_id=provider_id,
+        status=UsageStatus.UNKNOWN,
+        confidence=Confidence.LOCAL_CLI,
+        warnings=["Droid CLI status exposes current-session usage, not subscription quota."],
+        raw={"current_session": raw},
+    )
+
+
+def parse_opencode_stats(provider_id: str, text: str) -> CapacitySnapshot | None:
+    if "COST & TOKENS" not in text and "MODEL USAGE" not in text:
+        return None
+    raw: dict[str, float | int] = {}
+    money = re.search(r"Total Cost\s+\$(?P<cost>\d+(?:\.\d+)?)", text, re.I)
+    messages = re.search(r"Messages\s+(?P<messages>[\d,]+)", text, re.I)
+    sessions = re.search(r"Sessions\s+(?P<sessions>[\d,]+)", text, re.I)
+    if money:
+        raw["total_cost"] = float(money.group("cost"))
+    if messages:
+        raw["messages"] = int(messages.group("messages").replace(",", ""))
+    if sessions:
+        raw["sessions"] = int(sessions.group("sessions").replace(",", ""))
+    return CapacitySnapshot(
+        provider_id=provider_id,
+        status=UsageStatus.UNKNOWN,
+        confidence=Confidence.LOCAL_CLI,
+        warnings=["OpenCode stats expose local token/cost history, not subscription quota."],
+        raw=raw,
+    )
+
+
+def _status_from_remaining(remaining: float) -> UsageStatus:
+    if remaining <= 0:
+        return UsageStatus.LIMIT_REACHED
+    if remaining <= 15:
+        return UsageStatus.NEAR_LIMIT
+    return UsageStatus.AVAILABLE
+
+
+def _strip_ansi(text: str) -> str:
+    return re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", text)
+
+
+def _parse_devin_reset(text: str) -> datetime | None:
+    match = re.search(
+        r"Quota resets\s+(?P<month>[A-Z][a-z]+)\s+(?P<day>\d{1,2}),\s+(?P<time>\d{1,2}:\d{2}\s+[AP]M)\s+\(UTC(?P<offset>[+-]\d{1,2})\)",
+        text,
+    )
+    if not match:
+        return None
+    year = datetime.now().year
+    offset = timezone(timedelta(hours=int(match.group("offset"))))
+    try:
+        parsed = datetime.strptime(
+            f"{match.group('month')} {match.group('day')} {year} {match.group('time')}",
+            "%B %d %Y %I:%M %p",
+        )
+    except ValueError:
+        return None
+    reset_at = parsed.replace(tzinfo=offset)
+    if reset_at < datetime.now(offset) - timedelta(days=180):
+        reset_at = reset_at.replace(year=year + 1)
+    return reset_at
+
+
+def _extract_labeled_percent(text: str, label: str, name: str) -> UsageWindow | None:
+    pattern = re.compile(
+        rf"{re.escape(label)}(?P<context>.{{0,800}}?)(?=(?:Current session|Current week|\Z))",
+        re.I | re.S,
+    )
+    match = pattern.search(text)
+    if not match:
+        return None
+    context = match.group("context")
+    percent_match = re.search(
+        r"(?P<percent>\d+(?:\.\d+)?)%\s*(?P<direction>left|remaining|used)?",
+        context,
+        re.I,
+    )
+    if not percent_match:
+        return None
+    percent = float(percent_match.group("percent"))
+    direction = (percent_match.group("direction") or "remaining").lower()
+    if direction == "used":
+        used = percent
+        remaining = 100.0 - percent
+    else:
+        remaining = percent
+        used = 100.0 - percent
+    reset_match = re.search(r"resets?\s+(?:in\s+)?(?P<reset>[^\n\r|·]+)", context, re.I)
+    raw = f"{label}{context[:400]}"
+    if reset_match:
+        raw = f"{raw} reset {reset_match.group('reset').strip()}"
+    return UsageWindow(
+        name=name,
+        kind=_kind_from_name(name),
+        used_percent=max(0.0, min(100.0, used)),
+        remaining_percent=max(0.0, min(100.0, remaining)),
+        confidence=Confidence.LOCAL_CLI,
+        raw_text=raw.strip(),
+    )
+
+
+def _kind_from_name(name: str) -> UsageWindowKind:
+    if name == "session":
+        return UsageWindowKind.SESSION
+    if name == "weekly" or name.startswith("weekly_"):
+        return UsageWindowKind.WEEKLY
+    if name == "daily":
+        return UsageWindowKind.DAILY
+    if name == "5h":
+        return UsageWindowKind.FIVE_HOUR
+    if name in {"extra_usage", "on_demand"}:
+        return UsageWindowKind.ON_DEMAND
+    return UsageWindowKind.UNKNOWN

agentpool/usage/summary.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from agentpool.models import CapacitySnapshot, Confidence, ProviderDescriptor, UsageStatus
+
+
+def build_usage_summary(
+    snapshots: list[CapacitySnapshot],
+    min_remaining_percent: int = 10,
+    stale_after_seconds: int = 1800,
+    provider_descriptors: list[ProviderDescriptor] | None = None,
+) -> dict[str, Any]:
+    now = datetime.now(timezone.utc)
+    descriptor_by_id = {descriptor.id: descriptor for descriptor in provider_descriptors or []}
+    rows = {
+        snapshot.provider_id: _provider_summary(
+            snapshot,
+            min_remaining_percent=min_remaining_percent,
+            stale_after_seconds=stale_after_seconds,
+            now=now,
+            descriptor=descriptor_by_id.get(snapshot.provider_id),
+        )
+        for snapshot in sorted(snapshots, key=lambda item: item.provider_id)
+    }
+    next_provider, next_at = _next_available(rows)
+    return {
+        "checked_at": datetime.now(timezone.utc).isoformat(),
+        "providers": rows,
+        "min_remaining_percent": min_remaining_percent,
+        "next_available_provider": next_provider,
+        "next_available_at": next_at,
+        "counts": {
+            "total": len(rows),
+            "usable": sum(1 for row in rows.values() if row["usable"]),
+            "unusable": sum(1 for row in rows.values() if not row["usable"]),
+            "available": sum(1 for row in rows.values() if row["status"] == UsageStatus.AVAILABLE.value),
+            "near_limit": sum(1 for row in rows.values() if row["status"] == UsageStatus.NEAR_LIMIT.value),
+            "limit_reached": sum(1 for row in rows.values() if row["status"] == UsageStatus.LIMIT_REACHED.value),
+            "unknown": sum(1 for row in rows.values() if row["status"] == UsageStatus.UNKNOWN.value),
+            "unavailable": sum(1 for row in rows.values() if row["status"] == UsageStatus.UNAVAILABLE.value),
+        },
+    }
+
+
+def _provider_summary(
+    snapshot: CapacitySnapshot,
+    min_remaining_percent: int,
+    stale_after_seconds: int,
+    now: datetime,
+    descriptor: ProviderDescriptor | None = None,
+) -> dict[str, Any]:
+    windows = [
+        {
+            "name": window.name,
+            "kind": window.kind.value if hasattr(window.kind, "value") else str(window.kind),
+            "remaining_percent": window.remaining_percent,
+            "used_percent": window.used_percent,
+            "remaining_units": window.remaining_units,
+            "reset_at": window.reset_at.isoformat() if window.reset_at else None,
+            "confidence": window.confidence.value if hasattr(window.confidence, "value") else str(window.confidence),
+        }
+        for window in snapshot.windows
+    ]
+    age_seconds = max(0.0, (now - snapshot.checked_at).total_seconds())
+    stale = age_seconds > stale_after_seconds
+    usable, unusable_reason = _usable_reason(snapshot, windows, min_remaining_percent, descriptor, stale)
+    return {
+        "provider_id": snapshot.provider_id,
+        "status": snapshot.status.value if hasattr(snapshot.status, "value") else str(snapshot.status),
+        "confidence": snapshot.confidence.value if hasattr(snapshot.confidence, "value") else str(snapshot.confidence),
+        "installed": descriptor.installed if descriptor else None,
+        "auth_status": descriptor.auth.status if descriptor else None,
+        "usable": usable,
+        "unusable_reason": unusable_reason,
+        "stale": stale,
+        "age_seconds": age_seconds,
+        "checked_at": snapshot.checked_at.isoformat(),
+        "windows": windows,
+        "credits_remaining": snapshot.credits_remaining,
+        "warnings": snapshot.warnings,
+        "source": snapshot.raw.get("source"),
+        "summary": _summary_text(snapshot, windows),
+    }
+
+
+def _usable_reason(
+    snapshot: CapacitySnapshot,
+    windows: list[dict[str, Any]],
+    min_remaining_percent: int,
+    descriptor: ProviderDescriptor | None,
+    stale: bool,
+) -> tuple[bool, str | None]:
+    if descriptor and not descriptor.installed:
+        return False, "not_installed"
+    if descriptor and descriptor.auth.status in {"unauthenticated", "unavailable"}:
+        return False, f"auth_{descriptor.auth.status}"
+    status = snapshot.status.value if hasattr(snapshot.status, "value") else str(snapshot.status)
+    if status in {UsageStatus.LIMIT_REACHED.value, UsageStatus.UNAVAILABLE.value, UsageStatus.UNAUTHENTICATED.value}:
+        return False, status
+    if status == UsageStatus.UNKNOWN.value:
+        return False, "usage_unknown"
+    confidence = snapshot.confidence.value if hasattr(snapshot.confidence, "value") else str(snapshot.confidence)
+    allowed_confidence = {
+        Confidence.OFFICIAL.value,
+        Confidence.LOCAL_CLI.value,
+        Confidence.LOCAL_CONFIG.value,
+        Confidence.USER_CONFIGURED.value,
+    }
+    if confidence not in allowed_confidence:
+        return False, f"confidence_{confidence}"
+    if stale:
+        return False, "usage_stale"
+    for window in windows:
+        remaining = window["remaining_percent"]
+        if remaining is not None and remaining < min_remaining_percent:
+            return False, f"{window['name']}_below_{min_remaining_percent}_percent"
+    return True, None
+
+
+def _next_available(rows: dict[str, dict[str, Any]]) -> tuple[str | None, str | None]:
+    candidates: list[tuple[datetime, str]] = []
+    now = datetime.now(timezone.utc)
+    for provider_id, row in rows.items():
+        if row["usable"]:
+            continue
+        for window in row["windows"]:
+            reset_at = window.get("reset_at")
+            if not reset_at:
+                continue
+            try:
+                parsed = datetime.fromisoformat(reset_at)
+            except ValueError:
+                continue
+            if parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=timezone.utc)
+            if parsed > now:
+                candidates.append((parsed, provider_id))
+    if not candidates:
+        return None, None
+    reset_at, provider_id = min(candidates, key=lambda item: item[0])
+    return provider_id, reset_at.isoformat()
+
+
+def _summary_text(snapshot: CapacitySnapshot, windows: list[dict[str, Any]]) -> str:
+    parts: list[str] = []
+    seen: set[tuple[str, float | None, float | None]] = set()
+    for window in windows:
+        label = window["kind"] if window["kind"] != "unknown" else window["name"]
+        remaining = window["remaining_percent"]
+        key = (label, remaining, window["remaining_units"])
+        if key in seen:
+            continue
+        seen.add(key)
+        if remaining is not None:
+            parts.append(f"{label} {remaining:g}% left")
+        elif window["remaining_units"] is not None:
+            parts.append(f"{label} {window['remaining_units']:g} units left")
+    if snapshot.credits_remaining is not None:
+        parts.append(f"${snapshot.credits_remaining:g} credits")
+    if parts:
+        return ", ".join(parts)
+    if snapshot.warnings:
+        return "; ".join(snapshot.warnings)
+    return snapshot.status.value if hasattr(snapshot.status, "value") else str(snapshot.status)

agentpool/utils.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def new_session_id() -> str:
+    return f"ap_{uuid.uuid4().hex[:12]}"
+
+
+def repo_hash(path: Path) -> str:
+    return hashlib.sha256(str(path.resolve()).encode("utf-8")).hexdigest()[:16]
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True, default=str) + "\n")
+
+
+def append_jsonl(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(data, sort_keys=True, default=str) + "\n")
+
+
+def run_capture(args: list[str], cwd: Path | None = None, timeout: float = 10) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            args,
+            cwd=str(cwd) if cwd else None,
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        return subprocess.CompletedProcess(args, 124, exc.stdout or "", exc.stderr or "timed out")
+
+
+def expand_user_path(value: str) -> Path:
+    return Path(os.path.expandvars(value)).expanduser()