claude-dev-env 2.2.1 → 2.3.0

package/scripts/claude_chain_usage.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+"""Report remaining weekly usage for every account in the Claude chain.
+
+Loads ``~/.claude/claude-chain.json`` (or a path the caller names), probes each
+entry's weekly utilization through the usage-pause OAuth endpoint, and prints a
+JSON report. Ranking is available as an importable helper; ``run_claude``
+consumes that ranking to choose try order.
+
+::
+
+    python claude_chain_usage.py
+    {"accounts": [
+      {"command": "claude", "weekly_remaining_percent": 58.0},
+      {"command": "claude-ev", "weekly_remaining_percent": null, "error": "..."}
+    ]}
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.client
+import importlib.util
+import json
+import sys
+import urllib.error
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from types import ModuleType
+
+from dev_env_scripts_constants.claude_chain_constants import CHAIN_CONFIG_ERROR_EXIT_CODE
+from dev_env_scripts_constants.claude_chain_usage_constants import (
+    CLI_CONFIG_PATH_FLAG,
+    FULL_WEEKLY_PERCENT,
+    JSON_ACCOUNTS_KEY,
+    JSON_COMMAND_KEY,
+    JSON_ERROR_KEY,
+    JSON_WEEKLY_REMAINING_PERCENT_KEY,
+    NO_ACCESS_TOKEN_ERROR_TEMPLATE,
+    RESOLVE_USAGE_WINDOW_FILENAME,
+    RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE,
+    RESOLVE_USAGE_WINDOW_MODULE_NAME,
+    USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME,
+    USAGE_PAUSE_SKILL_DIRECTORY_NAME,
+    USAGE_PAUSE_SKILL_NAME,
+    USAGE_PROBE_FAILED_ERROR_TEMPLATE,
+    WEEKLY_UTILIZATION_MISSING_ERROR,
+)
+
+import claude_chain_runner as chain_runner
+
+WeeklyUtilizationProbe = Callable[[Path], float]
+
+
+class WeeklyUtilizationProbeError(Exception):
+    """Raised when the weekly_utilization_probe cannot measure one account."""
+
+
+@dataclass(frozen=True)
+class AccountUsageReport:
+    """One chain account's remaining weekly usage, or the reason it is unknown."""
+
+    command: str
+    weekly_remaining_percent: float | None
+    error: str | None = None
+
+
+def _default_credentials_path() -> Path:
+    usage_window_resolver = _load_resolve_usage_window_module()
+    return Path.home().joinpath(
+        *usage_window_resolver.ALL_CREDENTIALS_RELATIVE_PATH_PARTS
+    )
+
+
+def _credentials_path_for_entry(entry: chain_runner.ChainEntry) -> Path:
+    if entry.credentials_path is None:
+        return _default_credentials_path()
+    return Path(entry.credentials_path).expanduser()
+
+
+def _usage_pause_scripts_directory() -> Path:
+    package_root = Path(__file__).resolve().parent.parent
+    return (
+        package_root
+        / USAGE_PAUSE_SKILL_DIRECTORY_NAME
+        / USAGE_PAUSE_SKILL_NAME
+        / USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME
+    )
+
+
+def _discard_sys_path_entry(path_text: str) -> None:
+    if path_text in sys.path:
+        sys.path.remove(path_text)
+
+
+def _load_resolve_usage_window_module() -> ModuleType:
+    already_loaded = sys.modules.get(RESOLVE_USAGE_WINDOW_MODULE_NAME)
+    if already_loaded is not None:
+        return already_loaded
+    scripts_directory = _usage_pause_scripts_directory()
+    module_path = scripts_directory / RESOLVE_USAGE_WINDOW_FILENAME
+    if not module_path.is_file():
+        raise WeeklyUtilizationProbeError(
+            RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE.format(
+                module_path=module_path
+            )
+        )
+    scripts_directory_text = str(scripts_directory)
+    was_path_inserted = False
+    if scripts_directory_text not in sys.path:
+        sys.path.insert(0, scripts_directory_text)
+        was_path_inserted = True
+    is_module_ready = False
+    try:
+        module_specification = importlib.util.spec_from_file_location(
+            RESOLVE_USAGE_WINDOW_MODULE_NAME, module_path
+        )
+        if module_specification is None or module_specification.loader is None:
+            raise WeeklyUtilizationProbeError(
+                RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE.format(
+                    module_path=module_path
+                )
+            )
+        loaded_module = importlib.util.module_from_spec(module_specification)
+        sys.modules[RESOLVE_USAGE_WINDOW_MODULE_NAME] = loaded_module
+        module_specification.loader.exec_module(loaded_module)
+        is_module_ready = True
+    finally:
+        if not is_module_ready:
+            sys.modules.pop(RESOLVE_USAGE_WINDOW_MODULE_NAME, None)
+        if was_path_inserted:
+            _discard_sys_path_entry(scripts_directory_text)
+    return loaded_module
+
+
+def _probe_weekly_utilization(credentials_path: Path) -> float:
+    usage_window_resolver = _load_resolve_usage_window_module()
+    now = datetime.now().astimezone()
+    try:
+        access_token = usage_window_resolver.read_oauth_access_token(
+            credentials_path, now
+        )
+        if access_token is None:
+            raise WeeklyUtilizationProbeError(
+                NO_ACCESS_TOKEN_ERROR_TEMPLATE.format(credentials_path=credentials_path)
+            )
+        usage_payload = usage_window_resolver._fetch_usage_payload(access_token)
+    except WeeklyUtilizationProbeError:
+        raise
+    except (
+        urllib.error.URLError,
+        http.client.HTTPException,
+        TimeoutError,
+        OSError,
+        ValueError,
+    ) as probe_error:
+        raise WeeklyUtilizationProbeError(
+            USAGE_PROBE_FAILED_ERROR_TEMPLATE.format(error=probe_error)
+        ) from probe_error
+    usage_windows = usage_window_resolver.extract_usage_windows(usage_payload)
+    if usage_windows.weekly_utilization is None:
+        raise WeeklyUtilizationProbeError(WEEKLY_UTILIZATION_MISSING_ERROR)
+    return float(usage_windows.weekly_utilization)
+
+
+weekly_utilization_probe: WeeklyUtilizationProbe = _probe_weekly_utilization
+
+
+def weekly_remaining_from_utilization(weekly_utilization: float) -> float:
+    """Convert weekly utilization percent into remaining weekly percent.
+
+    ::
+
+        weekly_remaining_from_utilization(42.0) -> 58.0
+        weekly_remaining_from_utilization(9.0)  -> 91.0
+
+    Args:
+        weekly_utilization: Used weekly capacity on the 0–100 scale.
+
+    Returns:
+        Remaining weekly capacity on the same 0–100 scale.
+    """
+    return FULL_WEEKLY_PERCENT - weekly_utilization
+
+
+def _report_for_entry(
+    entry: chain_runner.ChainEntry,
+    active_probe: WeeklyUtilizationProbe,
+) -> AccountUsageReport:
+    try:
+        credentials_path = _credentials_path_for_entry(entry)
+        weekly_utilization = active_probe(credentials_path)
+    except (WeeklyUtilizationProbeError, ImportError, AttributeError) as probe_error:
+        return AccountUsageReport(
+            command=entry.command,
+            weekly_remaining_percent=None,
+            error=str(probe_error),
+        )
+    return AccountUsageReport(
+        command=entry.command,
+        weekly_remaining_percent=weekly_remaining_from_utilization(
+            weekly_utilization
+        ),
+    )
+
+
+def report_chain_weekly_usage(*, config_path: Path) -> list[AccountUsageReport]:
+    """Report remaining weekly usage for every account in the chain config.
+
+    ::
+
+        report_chain_weekly_usage(config_path=Path("chain.json"))
+        -> [AccountUsageReport("claude", 58.0), ...]
+
+    Uses the module-level ``weekly_utilization_probe`` (tests rebind it).
+
+    Args:
+        config_path: Chain configuration file to load.
+
+    Returns:
+        One report per chain entry, in config order.
+
+    Raises:
+        ChainConfigurationError: When the chain configuration cannot be loaded.
+    """
+    all_entries = chain_runner.load_chain(config_path)
+    return [
+        _report_for_entry(each_entry, weekly_utilization_probe)
+        for each_entry in all_entries
+    ]
+
+
+def _nulls_last_remaining_rank(report: AccountUsageReport) -> tuple[int, float]:
+    if report.weekly_remaining_percent is None:
+        return (1, 0.0)
+    return (0, -report.weekly_remaining_percent)
+
+
+def rank_accounts_by_weekly_remaining(
+    all_reports: list[AccountUsageReport],
+) -> list[AccountUsageReport]:
+    """Order reports by remaining weekly usage, highest first.
+
+    ::
+
+        [40%, 70%, null, 70%] -> [70% (earlier), 70% (later), 40%, null]
+
+    Ties keep config order. Unmeasurable accounts (null remaining) sort last.
+
+    Args:
+        all_reports: Reports in chain-config order.
+
+    Returns:
+        A new list ordered by remaining weekly percent descending.
+    """
+    return sorted(all_reports, key=_nulls_last_remaining_rank)
+
+
+def _account_report_to_json_mapping(
+    report: AccountUsageReport,
+) -> dict[str, str | float | None]:
+    if report.weekly_remaining_percent is None:
+        return {
+            JSON_COMMAND_KEY: report.command,
+            JSON_WEEKLY_REMAINING_PERCENT_KEY: None,
+            JSON_ERROR_KEY: report.error,
+        }
+    return {
+        JSON_COMMAND_KEY: report.command,
+        JSON_WEEKLY_REMAINING_PERCENT_KEY: report.weekly_remaining_percent,
+    }
+
+
+def reports_to_json_payload(
+    all_reports: list[AccountUsageReport],
+) -> dict[str, list[dict[str, str | float | None]]]:
+    """Build the CLI JSON payload for a list of account reports.
+
+    ::
+
+        reports_to_json_payload([AccountUsageReport("claude", 58.0)])
+        -> {"accounts": [{"command": "claude", "weekly_remaining_percent": 58.0}]}
+
+    Args:
+        all_reports: Reports in the order they should appear in the payload.
+
+    Returns:
+        The ``{"accounts": [...]}`` envelope.
+    """
+    return {
+        JSON_ACCOUNTS_KEY: [
+            _account_report_to_json_mapping(each_report)
+            for each_report in all_reports
+        ]
+    }
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Report remaining weekly usage for every account in the Claude chain."
+        )
+    )
+    parser.add_argument(
+        CLI_CONFIG_PATH_FLAG,
+        dest="config_path",
+        default=None,
+        help="Path to claude-chain.json; defaults to the per-user chain config.",
+    )
+    return parser
+
+
+def main(all_command_arguments: list[str]) -> int:
+    """Probe the chain and print the weekly-usage JSON report on stdout.
+
+    ::
+
+        main(["--config-path", "chain.json"]) -> 0  # JSON on stdout
+        main(["--config-path", "missing.json"]) -> 3  # error on stderr
+
+    Args:
+        all_command_arguments: The argument vector after the program name.
+
+    Returns:
+        Zero on success, or the chain-config error exit code when the config
+        cannot be loaded.
+    """
+    parser = _build_argument_parser()
+    parsed_arguments = parser.parse_args(all_command_arguments)
+    resolved_config_path = (
+        Path(parsed_arguments.config_path)
+        if parsed_arguments.config_path is not None
+        else chain_runner.chain_config_path()
+    )
+    try:
+        all_reports = report_chain_weekly_usage(config_path=resolved_config_path)
+    except chain_runner.ChainConfigurationError as configuration_error:
+        print(str(configuration_error), file=sys.stderr)
+        return CHAIN_CONFIG_ERROR_EXIT_CODE
+    print(json.dumps(reports_to_json_payload(all_reports), ensure_ascii=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -8,11 +8,12 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 |---|---|
 | `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
 | `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
-| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys, invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes |
+| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes |
+| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
 | `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, and `spawn_grok_batch.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, timeouts and turn caps (including launch-failure return code and post-kill grace), ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
-| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review high --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers |
+| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review xhigh --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers |
 | `__init__.py` | Empty package marker |
 
 ## Convention
 
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.

package/scripts/dev_env_scripts_constants/claude_chain_constants.py

@@ -18,6 +18,9 @@ CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 CONFIG_FILENAME: str = "claude-chain.json"
 """Real chain-configuration filename read from the user's home directory."""
 
+CHAIN_USAGE_MODULE_NAME: str = "claude_chain_usage"
+"""Import name of the weekly-usage report module loaded lazily by the runner."""
+
 EXAMPLE_CONFIG_FILENAME: str = "claude-chain.example.json"
 """Committed template filename referenced in the config-error guidance."""
 
@@ -30,6 +33,9 @@ CONFIG_COMMAND_KEY: str = "command"
 CONFIG_EXTRA_ARGS_KEY: str = "extra_args"
 """Chain-entry key holding per-account arguments appended to each invocation."""
 
+CONFIG_CREDENTIALS_PATH_KEY: str = "credentials_path"
+"""Optional chain-entry key naming that account's OAuth credentials file path."""
+
 ALL_USAGE_LIMIT_SIGNATURES: tuple[str, ...] = (
     "hit your session limit",
     "usage limit reached",
@@ -91,9 +97,15 @@ CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON: str = (
 )
 """Reason detail when a chain entry's extra_args value is the wrong shape."""
 
+CONFIG_ENTRY_CREDENTIALS_PATH_INVALID_REASON: str = (
+    "a chain entry's 'credentials_path' is not a non-empty string"
+)
+"""Reason detail when a chain entry's credentials_path value is the wrong shape."""
+
 CONFIG_MISSING_MESSAGE_TEMPLATE: str = (
     "Claude chain config not found at {config_path}. Copy {example_filename} to "
-    "{config_path} and list your logged-in claude binaries in fallback order."
+    "{config_path} and list your account binaries. Try order comes from weekly "
+    "remaining; config order is the tiebreak."
 )
 """Guidance shown when the config file is absent."""
 

package/scripts/dev_env_scripts_constants/claude_chain_usage_constants.py

@@ -0,0 +1,58 @@
+"""Named constants for the claude chain weekly-usage report tool.
+
+Per the project's configuration conventions, every scalar and structural
+constant the usage reporter needs lives here rather than inline in the module.
+"""
+
+from __future__ import annotations
+
+FULL_WEEKLY_PERCENT: float = 100.0
+"""Percent scale ceiling for weekly utilization (remaining = this minus used)."""
+
+USAGE_PAUSE_SKILL_DIRECTORY_NAME: str = "skills"
+"""Package-root directory name that holds skill trees (sibling of ``scripts/``)."""
+
+USAGE_PAUSE_SKILL_NAME: str = "usage-pause"
+"""Skill directory name under ``skills/`` that owns the OAuth usage probe."""
+
+USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+"""Directory under the usage-pause skill that holds the OAuth probe module."""
+
+RESOLVE_USAGE_WINDOW_MODULE_NAME: str = "resolve_usage_window"
+"""Module name of the usage-pause OAuth probe loader."""
+
+RESOLVE_USAGE_WINDOW_FILENAME: str = "resolve_usage_window.py"
+"""Filename of the usage-pause OAuth probe module on disk."""
+
+JSON_ACCOUNTS_KEY: str = "accounts"
+"""Top-level key in the CLI JSON report holding the per-account list."""
+
+JSON_COMMAND_KEY: str = "command"
+"""Per-account JSON key naming the chain binary."""
+
+JSON_WEEKLY_REMAINING_PERCENT_KEY: str = "weekly_remaining_percent"
+"""Per-account JSON key for remaining weekly usage percent (or null)."""
+
+JSON_ERROR_KEY: str = "error"
+"""Per-account JSON key carrying the unmeasurable-reason string."""
+
+CLI_CONFIG_PATH_FLAG: str = "--config-path"
+"""CLI flag that overrides the chain configuration file path."""
+
+NO_ACCESS_TOKEN_ERROR_TEMPLATE: str = (
+    "no usable bearer token from the OAuth credential file at {credentials_path}"
+)
+"""Error when the entry credential file yields no usable OAuth bearer."""
+
+WEEKLY_UTILIZATION_MISSING_ERROR: str = (
+    "usage response carried no weekly utilization"
+)
+"""Error when the OAuth usage payload has no readable seven_day utilization."""
+
+USAGE_PROBE_FAILED_ERROR_TEMPLATE: str = "usage probe failed: {error}"
+"""Error when the OAuth usage HTTP probe raises."""
+
+RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE: str = (
+    "usage-pause probe module not found at {module_path}"
+)
+"""Error when the resolve_usage_window script cannot be located on disk."""

package/scripts/dev_env_scripts_constants/code_review_constants.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 CODE_REVIEW_SLASH_COMMAND: str = "/code-review"
 """Built-in Claude Code slash command that runs the repository review."""
 
-CODE_REVIEW_EFFORT: str = "high"
+CODE_REVIEW_EFFORT: str = "xhigh"
 """Effort level passed to the built-in review slash command."""
 
 CODE_REVIEW_FIX_FLAG: str = "--fix"

package/scripts/dev_env_scripts_constants/timing.py

@@ -13,5 +13,5 @@ DEFAULT_POLL_INTERVAL: int = 30
 WORKER_STAGGER_SECONDS: int = 15
 """Seconds between staggered headless grok worker process starts in a batch."""
 
-DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS: int = 600
+DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS: int = 2400
 """Default timeout applied to one headless `/code-review` chain invocation, in seconds."""