token-runway 0.1.0__py3-none-any.whl

token_runway/__init__.py

@@ -0,0 +1,6 @@
+"""Top-level package for Token Runway."""
+
+from token_runway.cli import __version__, main
+from token_runway.server import TokenRunwayServer
+
+__all__ = ["__version__", "main", "TokenRunwayServer"]

token_runway/__main__.py

@@ -0,0 +1,7 @@
+"""Module entrypoint for python -m token_runway."""
+
+import sys
+from token_runway.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

token_runway/cli.py

@@ -0,0 +1,179 @@
+"""Command-line interface for Token Runway."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from typing import List, Optional
+
+from token_runway.injector import get_ide_config_targets, inject_into_file
+from token_runway.server import TokenRunwayServer
+from token_runway.sources import fetch_all_runways
+from token_runway.sources.claude import find_claude_token
+
+__version__ = "0.1.0"
+
+
+def format_status_badge(status: str) -> str:
+    """Simple ANSI terminal color badge."""
+    if status == "critical":
+        return "\033[91m● CRITICAL\033[0m"
+    if status == "warning":
+        return "\033[93m▲ WARNING\033[0m"
+    if status == "ok":
+        return "\033[92m✔ OK\033[0m"
+    if status == "unlimited":
+        return "\033[96m∞ UNLIMITED\033[0m"
+    if status == "not_on_plan":
+        return "\033[90m- NOT ON PLAN\033[0m"
+    return status.upper()
+
+
+def cmd_check() -> int:
+    """Print a terminal table of active token quotas across all providers."""
+    print("\n\033[1m=== Token Runway: Live Quota Telemetry ===\033[0m\n")
+    readings = fetch_all_runways()
+
+    for key, r in readings.items():
+        title = f"\033[1;34m{r.display_name}\033[0m"
+        if r.plan:
+            title += f" \033[90m(Plan: {r.plan})\033[0m"
+        print(title)
+
+        if not r.available:
+            print(f"  \033[90mUnavailable: {r.error_message}\033[0m\n")
+            continue
+
+        if not r.windows:
+            print("  \033[90mNo active quota windows reported.\033[0m\n")
+            continue
+
+        for w in r.windows:
+            badge = format_status_badge(w.status)
+            line = f"  • {w.name:<26} {badge:<22}"
+
+            if w.used_pct is not None:
+                line += f" Used: {w.used_pct:>3}%"
+            if w.remaining_pct is not None:
+                line += f"  (Remaining: {w.remaining_pct:>5}%)"
+            if w.remaining_count is not None:
+                if w.total_entitlement is not None:
+                    line += f"  [{w.remaining_count}/{w.total_entitlement}]"
+                else:
+                    line += f"  [{w.remaining_count}]"
+            if w.resets_in_minutes is not None:
+                if w.resets_in_minutes < 60:
+                    line += f"  (Resets in {w.resets_in_minutes}m)"
+                elif w.resets_in_minutes < 1440:
+                    line += f"  (Resets in {w.resets_in_minutes // 60}h {w.resets_in_minutes % 60}m)"
+                else:
+                    line += f"  (Resets in {w.resets_in_minutes // 1440}d {(w.resets_in_minutes % 1440) // 60}h)"
+
+            print(line)
+        print()
+
+    return 0
+
+
+def cmd_doctor() -> int:
+    """Diagnose local CLI tools, credentials, and network connectivity."""
+    print("\n\033[1m=== Token Runway: Doctor ===\033[0m\n")
+
+    # 1. Claude
+    token = find_claude_token()
+    if token:
+        print("  \033[92m✔ Claude Code:\033[0m Credentials found")
+    else:
+        print("  \033[93m▲ Claude Code:\033[0m No credentials found in ~/.claude/.credentials.json")
+
+    # 2. Antigravity CLI (`agy`)
+    if shutil.which("agy"):
+        print("  \033[92m✔ Antigravity CLI (`agy`):\033[0m Found in PATH")
+    else:
+        print("  \033[90m- Antigravity CLI (`agy`):\033[0m Not installed or not in PATH")
+
+    # 3. GitHub CLI (`gh`)
+    if shutil.which("gh"):
+        print("  \033[92m✔ GitHub CLI (`gh`):\033[0m Found in PATH")
+    else:
+        print("  \033[90m- GitHub CLI (`gh`):\033[0m Not installed or not in PATH")
+
+    # 4. Google Colab CLI (`colab`)
+    if shutil.which("colab"):
+        print("  \033[92m✔ Google Colab CLI (`colab`):\033[0m Found in PATH")
+    else:
+        print("  \033[90m- Google Colab CLI (`colab`):\033[0m Not installed or not in PATH")
+
+    print("\nChecking live endpoints...")
+    readings = fetch_all_runways()
+    for name, r in readings.items():
+        if r.available:
+            print(f"  \033[92m✔ {r.display_name}:\033[0m Connected ({len(r.windows)} quota windows active)")
+        else:
+            print(f"  \033[93m▲ {r.display_name}:\033[0m {r.error_message}")
+
+    print("\nDoctor check completed.\n")
+    return 0
+
+
+def cmd_inject(mode: str = "auto") -> int:
+    """Inject Token Runway into detected AI IDE configuration files."""
+    print("\n\033[1m=== Token Runway: IDE Injector ===\033[0m\n")
+    targets = get_ide_config_targets()
+    injected_count = 0
+
+    for ide_name, path in targets:
+        try:
+            inject_into_file(path, mode=mode)
+            print(f"  \033[92m✔ {ide_name}:\033[0m Injected configuration into {path}")
+            injected_count += 1
+        except Exception as e:
+            print(f"  \033[91m✖ {ide_name}:\033[0m Failed to update {path}: {e}")
+
+    print(f"\nInjected token-runway entry into {injected_count} IDE configuration(s).\n")
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="token-runway",
+        description="Model Context Protocol (MCP) server for real-time token runway & quota awareness.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"token-runway {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Subcommands
+    subparsers.add_parser("run", help="Run stdio MCP server (default when no command given).")
+    subparsers.add_parser("check", help="Print terminal table of active quotas.")
+    subparsers.add_parser("doctor", help="Check local tools, credentials, and API connectivity.")
+
+    inject_parser = subparsers.add_parser("inject", help="Auto-inject MCP server into Claude Desktop, Cursor, etc.")
+    inject_parser.add_argument(
+        "--mode",
+        choices=["auto", "uvx", "pip"],
+        default="auto",
+        help="Command launch mode in IDE configs (default: auto).",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        return cmd_check()
+    elif args.command == "doctor":
+        return cmd_doctor()
+    elif args.command == "inject":
+        return cmd_inject(mode=args.mode)
+    else:
+        # Default behavior: run MCP stdio server
+        server = TokenRunwayServer()
+        try:
+            server.run_stdio()
+            return 0
+        except (KeyboardInterrupt, BrokenPipeError):
+            return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

token_runway/injector/__init__.py

@@ -0,0 +1,9 @@
+"""Config injector utilities for Token Runway."""
+
+from token_runway.injector.config_injector import (
+    build_mcp_entry,
+    get_ide_config_targets,
+    inject_into_file,
+)
+
+__all__ = ["build_mcp_entry", "get_ide_config_targets", "inject_into_file"]

token_runway/injector/config_injector.py

@@ -0,0 +1,80 @@
+"""Multi-IDE configuration detector and one-click injector for Token Runway."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+def get_ide_config_targets() -> List[Tuple[str, Path]]:
+    """Return a list of known (IDE_Name, config_path) tuples for the current OS."""
+    targets = []
+    home = Path.home()
+
+    # 1. Claude Desktop
+    if sys.platform == "darwin":
+        targets.append(("Claude Desktop", home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"))
+    elif sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            targets.append(("Claude Desktop", Path(appdata) / "Claude" / "claude_desktop_config.json"))
+    else:
+        targets.append(("Claude Desktop", home / ".config" / "Claude" / "claude_desktop_config.json"))
+
+    # 2. Cursor
+    targets.append(("Cursor", home / ".cursor" / "mcp.json"))
+
+    # 3. Claude Code
+    targets.append(("Claude Code", home / ".claude" / "mcp.json"))
+
+    # 4. Antigravity
+    targets.append(("Antigravity", home / ".gemini" / "antigravity-cli" / "mcp_config.json"))
+
+    # 5. Windsurf
+    targets.append(("Windsurf", home / ".codeium" / "windsurf" / "mcp_config.json"))
+
+    return targets
+
+
+def build_mcp_entry(mode: str = "auto") -> Dict[str, Any]:
+    """Generate the MCP server entry dictionary."""
+    if mode == "uvx" or (mode == "auto" and shutil.which("uvx")):
+        return {
+            "command": "uvx",
+            "args": ["token-runway"],
+            "env": {"PYTHONUNBUFFERED": "1"},
+        }
+    else:
+        python_exe = sys.executable
+        return {
+            "command": python_exe,
+            "args": ["-m", "token_runway"],
+            "env": {"PYTHONUNBUFFERED": "1"},
+        }
+
+
+def inject_into_file(path: Path, entry_name: str = "token-runway", mode: str = "auto") -> bool:
+    """Inject or update the token-runway MCP server definition into target config."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data: Dict[str, Any] = {}
+    if path.is_file():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            data = {}
+
+    # Root key is typically "mcpServers"
+    if "mcpServers" not in data or not isinstance(data["mcpServers"], dict):
+        data["mcpServers"] = {}
+
+    data["mcpServers"][entry_name] = build_mcp_entry(mode)
+
+    tmp_path = path.with_suffix(".tmp")
+    tmp_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    tmp_path.replace(path)
+    return True

token_runway/server/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server implementation for Token Runway."""
+
+from token_runway.server.server import TokenRunwayServer
+
+__all__ = ["TokenRunwayServer"]

token_runway/server/advice.py

@@ -0,0 +1,84 @@
+"""Meta-cognitive reasoning engine for assessing action feasibility against active quotas."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from token_runway.sources.base import ProviderReading
+
+
+def evaluate_action_feasibility(
+    readings: Dict[str, ProviderReading],
+    action_type: str = "general",
+    intensity: str = "medium",  # "low", "medium", "high"
+    target_provider: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Evaluate whether an agent should proceed with a resource-intensive action."""
+    action_type = action_type.lower()
+    intensity = intensity.lower()
+
+    # Identify primary active provider constraints
+    providers_to_check = [target_provider] if target_provider and target_provider in readings else list(readings.keys())
+
+    highest_used_pct = 0
+    most_constrained_provider = None
+    most_constrained_window = None
+    mins_to_reset = None
+
+    for p_name in providers_to_check:
+        reading = readings.get(p_name)
+        if not reading or not reading.available:
+            continue
+        for w in reading.windows:
+            if w.used_pct is not None and w.used_pct > highest_used_pct:
+                highest_used_pct = w.used_pct
+                most_constrained_provider = reading.display_name
+                most_constrained_window = w.name
+                mins_to_reset = w.resets_in_minutes
+
+    recommendation = "proceed"
+    strategies: List[str] = []
+    reasoning: str = ""
+
+    if highest_used_pct >= 95:
+        recommendation = "pause_or_downgrade"
+        reasoning = (
+            f"Quota is critically constrained ({highest_used_pct}% used on {most_constrained_provider} {most_constrained_window})."
+        )
+        if mins_to_reset is not None and mins_to_reset <= 30:
+            strategies.append(
+                f"Window resets in ~{mins_to_reset} minutes. Defer heavy work and perform lightweight local tasks."
+            )
+        strategies.append("Prohibit parallel subagent fan-outs; execute one step at a time.")
+        strategies.append("Read narrow line ranges (under 100 lines) instead of loading full files into context.")
+        strategies.append("Route subagent prompts to lightweight models (Flash/Haiku) if model selection is supported.")
+    elif highest_used_pct >= 80:
+        if intensity == "high":
+            recommendation = "downgrade_strategy"
+            reasoning = (
+                f"Quota headroom is tight ({highest_used_pct}% used on {most_constrained_provider}). High-intensity operations risk lockouts."
+            )
+            strategies.append("Downgrade multi-agent broad searches to targeted ripgrep / grep commands.")
+            strategies.append("Summarize long context before launching further turns.")
+        else:
+            recommendation = "proceed_with_caution"
+            reasoning = f"Headroom is moderate ({highest_used_pct}% used). Standard actions permitted."
+            strategies.append("Monitor token usage after this turn.")
+    else:
+        recommendation = "proceed"
+        reasoning = f"Healthy headroom ({highest_used_pct}% maximum utilization across active providers)."
+        strategies.append("Full operational capacity available for multi-agent workflows and deep research.")
+
+    return {
+        "verdict": recommendation,
+        "max_utilization_pct": highest_used_pct,
+        "bottleneck": {
+            "provider": most_constrained_provider,
+            "window": most_constrained_window,
+            "resets_in_minutes": mins_to_reset,
+        }
+        if most_constrained_provider
+        else None,
+        "analysis": reasoning,
+        "preservation_strategies": strategies,
+    }

token_runway/server/protocol.py

@@ -0,0 +1,38 @@
+"""JSON-RPC 2.0 protocol definitions and message envelopes for MCP."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, Optional, Union
+
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+MCP_PROTOCOL_VERSION = "2024-11-05"
+
+
+def make_response(req_id: Union[int, str, None], result: Any) -> Dict[str, Any]:
+    """Construct a JSON-RPC 2.0 success response envelope."""
+    return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+
+def make_error(
+    req_id: Union[int, str, None], code: int, message: str, data: Optional[Any] = None
+) -> Dict[str, Any]:
+    """Construct a JSON-RPC 2.0 error response envelope."""
+    err: Dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "id": req_id, "error": err}
+
+
+def write_message(msg: Dict[str, Any], out_stream=None) -> None:
+    """Serialize and write a JSON-RPC message line followed by a newline."""
+    stream = out_stream or sys.stdout
+    line = json.dumps(msg, ensure_ascii=False)
+    stream.write(line + "\n")
+    stream.flush()

token_runway/server/server.py

@@ -0,0 +1,255 @@
+"""Stdio-based Model Context Protocol (MCP) server for Token Runway."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from typing import Any, Dict, List, Optional
+
+from token_runway.server.advice import evaluate_action_feasibility
+from token_runway.server.protocol import (
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    INVALID_REQUEST,
+    MCP_PROTOCOL_VERSION,
+    METHOD_NOT_FOUND,
+    make_error,
+    make_response,
+    write_message,
+)
+from token_runway.sources import fetch_all_runways
+from token_runway.sources.base import ProviderReading
+
+
+class TokenRunwayServer:
+    """Zero-dependency stdio MCP server exposing token quotas and advice."""
+
+    def __init__(self, cache_ttl: float = 30.0):
+        self.cache_ttl = cache_ttl
+        self._cached_readings: Optional[Dict[str, ProviderReading]] = None
+        self._cache_time: float = 0.0
+
+    def get_readings(self, force_refresh: bool = False) -> Dict[str, ProviderReading]:
+        now = time.monotonic()
+        if force_refresh or self._cached_readings is None or (now - self._cache_time) > self.cache_ttl:
+            self._cached_readings = fetch_all_runways()
+            self._cache_time = now
+        return self._cached_readings
+
+    def handle_request(self, req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        if not isinstance(req, dict) or req.get("jsonrpc") != "2.0":
+            return make_error(req.get("id") if isinstance(req, dict) else None, INVALID_REQUEST, "Invalid JSON-RPC request")
+
+        method = req.get("method")
+        req_id = req.get("id")
+        params = req.get("params") or {}
+
+        # Notifications (no id)
+        if req_id is None:
+            if method == "notifications/initialized":
+                return None
+            return None
+
+        # RPC Methods
+        if method == "initialize":
+            return make_response(
+                req_id,
+                {
+                    "protocolVersion": MCP_PROTOCOL_VERSION,
+                    "capabilities": {
+                        "tools": {},
+                        "resources": {},
+                        "prompts": {},
+                    },
+                    "serverInfo": {
+                        "name": "token-runway",
+                        "version": "0.1.0",
+                    },
+                },
+            )
+
+        if method == "ping":
+            return make_response(req_id, {})
+
+        if method == "tools/list":
+            return make_response(req_id, {"tools": self._list_tools()})
+
+        if method == "tools/call":
+            return self._call_tool(req_id, params)
+
+        if method == "resources/list":
+            return make_response(req_id, {"resources": self._list_resources()})
+
+        if method == "resources/read":
+            return self._read_resource(req_id, params)
+
+        if method == "prompts/list":
+            return make_response(req_id, {"prompts": self._list_prompts()})
+
+        if method == "prompts/get":
+            return self._get_prompt(req_id, params)
+
+        return make_error(req_id, METHOD_NOT_FOUND, f"Method not found: {method}")
+
+    def _list_tools(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "check_runway",
+                "description": (
+                    "Inspect current token quotas, utilization percentages, remaining capacity, "
+                    "and reset countdowns across Claude, Gemini, Antigravity, GitHub Copilot, and Colab."
+                ),
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "refresh": {
+                            "type": "boolean",
+                            "description": "Bypass cache and force an immediate re-fetch from all provider CLIs/APIs.",
+                            "default": False,
+                        },
+                        "provider": {
+                            "type": "string",
+                            "description": "Optional specific provider to filter ('claude', 'gemini', 'antigravity', 'copilot', 'colab').",
+                        },
+                    },
+                },
+            },
+            {
+                "name": "assess_action",
+                "description": (
+                    "Meta-cognitive evaluation of whether a proposed action (e.g. running multiple parallel subagents, "
+                    "reading massive files, or continuous test loops) is justified given current remaining quotas and reset timers."
+                ),
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "action_type": {
+                            "type": "string",
+                            "description": "Type of action planned ('subagent_fanout', 'large_file_dump', 'deep_research', 'targeted_edit', 'continuous_loop').",
+                            "default": "general",
+                        },
+                        "intensity": {
+                            "type": "string",
+                            "enum": ["low", "medium", "high"],
+                            "description": "Estimated token burn intensity of the action.",
+                            "default": "medium",
+                        },
+                        "provider": {
+                            "type": "string",
+                            "description": "Target provider whose limits you want to evaluate against (optional).",
+                        },
+                    },
+                },
+            },
+        ]
+
+    def _call_tool(self, req_id: Any, params: Dict[str, Any]) -> Dict[str, Any]:
+        name = params.get("name")
+        args = params.get("arguments") or {}
+
+        if name == "check_runway":
+            force = bool(args.get("refresh", False))
+            provider_filter = args.get("provider")
+            readings = self.get_readings(force_refresh=force)
+
+            if provider_filter and provider_filter.lower() in readings:
+                data = {provider_filter.lower(): readings[provider_filter.lower()].to_dict()}
+            else:
+                data = {k: v.to_dict() for k, v in readings.items()}
+
+            text = json.dumps(data, indent=2)
+            return make_response(req_id, {"content": [{"type": "text", "text": text}]})
+
+        if name == "assess_action":
+            action_type = args.get("action_type", "general")
+            intensity = args.get("intensity", "medium")
+            provider = args.get("provider")
+            readings = self.get_readings()
+            assessment = evaluate_action_feasibility(readings, action_type, intensity, provider)
+            text = json.dumps(assessment, indent=2)
+            return make_response(req_id, {"content": [{"type": "text", "text": text}]})
+
+        return make_error(req_id, INVALID_PARAMS, f"Unknown tool name: {name}")
+
+    def _list_resources(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "uri": "runway://status",
+                "name": "Live Token Runway Telemetry",
+                "description": "Real-time snapshot of remaining limits and countdowns across all providers.",
+                "mimeType": "application/json",
+            }
+        ]
+
+    def _read_resource(self, req_id: Any, params: Dict[str, Any]) -> Dict[str, Any]:
+        uri = params.get("uri")
+        if uri == "runway://status":
+            readings = self.get_readings()
+            data = {k: v.to_dict() for k, v in readings.items()}
+            return make_response(
+                req_id,
+                {
+                    "contents": [
+                        {
+                            "uri": uri,
+                            "mimeType": "application/json",
+                            "text": json.dumps(data, indent=2),
+                        }
+                    ]
+                },
+            )
+        return make_error(req_id, INVALID_PARAMS, f"Unknown resource URI: {uri}")
+
+    def _list_prompts(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "runway_governance",
+                "description": "Self-governance guidelines for operating under token rate-limits and quotas.",
+            }
+        ]
+
+    def _get_prompt(self, req_id: Any, params: Dict[str, Any]) -> Dict[str, Any]:
+        prompt_name = params.get("name")
+        if prompt_name == "runway_governance":
+            prompt_text = (
+                "You are an AI agent equipped with real-time awareness of your token quotas via Token Runway.\n\n"
+                "Before initiating resource-heavy operations (e.g. fanning out multiple subagents, dumping whole files >500 lines, "
+                "or running unbounded search loops), call `assess_action` or `check_runway`.\n\n"
+                "- If utilization is >=95%: Switch to quota-preserving strategies (surgical line edits, targeted ripgrep, sequential steps).\n"
+                "- If reset is within 20 minutes and quota is high: Defer heavy work and perform lightweight verification.\n"
+                "- If utilization is <80%: You have full operational headroom."
+            )
+            return make_response(
+                req_id,
+                {
+                    "description": "Runway governance instructions",
+                    "messages": [
+                        {
+                            "role": "user",
+                            "content": {"type": "text", "text": prompt_text},
+                        }
+                    ],
+                },
+            )
+        return make_error(req_id, INVALID_PARAMS, f"Unknown prompt: {prompt_name}")
+
+    def run_stdio(self) -> None:
+        """Run the MCP server event loop over standard input and standard output."""
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except Exception as e:
+                write_message(make_error(None, -32700, f"Parse error: {e}"))
+                continue
+
+            try:
+                resp = self.handle_request(msg)
+                if resp is not None:
+                    write_message(resp)
+            except Exception as e:
+                req_id = msg.get("id") if isinstance(msg, dict) else None
+                write_message(make_error(req_id, INTERNAL_ERROR, f"Internal server error: {e}"))