headroom-kit 0.1.0__py3-none-any.whl

headroom_kit/__init__.py

@@ -0,0 +1 @@
+"""Launch existing coding agents through a local Headroom proxy."""

headroom_kit/__main__.py

@@ -0,0 +1,5 @@
+"""Support python -m headroom_kit."""
+
+from headroom_kit.cli import main
+
+raise SystemExit(main())

headroom_kit/_owner.py

@@ -0,0 +1,14 @@
+"""Private detached owner. Not a console script."""
+
+import signal
+import sys
+
+from headroom_kit.proxy import owner_main
+from headroom_kit.runtime import stop
+
+if __name__ == "__main__":
+    # The owner is a new session. Without these, SIGTERM/SIGHUP skip cleanup
+    # and the proxy child keeps the port and control socket.
+    for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        signal.signal(sig, stop)
+    sys.exit(owner_main())

headroom_kit/_serve.py

@@ -0,0 +1,8 @@
+"""Private proxy server. Not a console script."""
+
+import sys
+
+from headroom_kit.proxy import serve_main
+
+if __name__ == "__main__":
+    sys.exit(serve_main())

headroom_kit/cli.py

@@ -0,0 +1,190 @@
+"""Public command surface for the installed Headroom Kit package."""
+
+import importlib.metadata
+import signal
+import subprocess
+import sys
+from collections.abc import Sequence
+
+from headroom_kit.copilot import run_copilot_auth
+from headroom_kit.proxy import management
+from headroom_kit.runtime import (
+    KitError,
+    executable,
+    installed_headroom_version,
+    load_config,
+    merge_config,
+    read_config,
+    run_agent,
+    say,
+    stop,
+    validate,
+)
+from headroom_kit.session import preflight, session
+
+AGENTS = {
+    "codex": "codex-headroom",
+    "codex-app": "codex-app-headroom",
+    "copilot": "copilot-headroom",
+    "copilot-vscode": "copilot-vscode-headroom",
+    "pi": "pi-headroom",
+    "opencode": "opencode-headroom",
+}
+CLI_AGENTS = ("codex-headroom", "copilot-headroom", "pi-headroom", "opencode-headroom")
+GUI_AGENTS = ("codex-app-headroom", "copilot-vscode-headroom")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        signal.signal(sig, stop)
+    try:
+        return dispatch(list(sys.argv[1:] if argv is None else argv))
+    except KitError as error:
+        say(str(error))
+    except (OSError, subprocess.SubprocessError):
+        say("A local process or file operation failed. Check paths, permissions, and disk space.")
+    return 1
+
+
+def dispatch(argv: list[str]) -> int:
+    if not argv or argv == ["--help"] or argv == ["-h"]:
+        print_help()
+        return 0 if argv else 2
+    if argv == ["--version"]:
+        return print_version()
+    config, rest = take_config(argv)
+    if not rest:
+        print_help()
+        return 2
+    command, *args = rest
+    if command == "copilot-auth":
+        return run_copilot_auth(args)
+    if command == "status":
+        return status(args)
+    if command == "stop":
+        return management(["stop", *args])
+    if command == "run":
+        return run(config, args)
+    if command in ("--help", "-h"):
+        print_help()
+        return 0
+    raise KitError(f"Unknown command {command!r}. Run headroom-kit --help.")
+
+
+def take_config(argv: list[str]) -> tuple[str | None, list[str]]:
+    if not argv or argv[0] != "--config":
+        return None, argv
+    if len(argv) < 2 or not argv[1] or argv[1].startswith("-"):
+        raise KitError("--config requires a path to a JSON object.")
+    return argv[1], argv[2:]
+
+
+def status(args: list[str]) -> int:
+    if args:
+        raise KitError("status does not take arguments. Run headroom-kit status.")
+    return management(["status"])
+
+
+def run(config: str | None, args: list[str]) -> int:
+    if not args or args[0] in ("--help", "-h"):
+        print_run_help()
+        return 0
+    agent, *rest = args
+    command = AGENTS.get(agent)
+    if command is None:
+        raise KitError(
+            f"Unknown agent {agent!r}. Choose {', '.join(AGENTS)}. Put agent arguments after --."
+        )
+    agent_args = agent_arguments(rest)
+    if forwards_help(command, agent_args):
+        return forward_agent(config, command, agent_args)
+    cfg = load_config(config)
+    validate(cfg)
+    return session(cfg, command, agent_args, installed_headroom_version())
+
+
+def agent_arguments(args: list[str]) -> list[str]:
+    if not args or args[0] != "--":
+        raise KitError("Put agent arguments after --. Example: headroom-kit run codex --")
+    return args[1:]
+
+
+def forwards_help(command: str, args: list[str]) -> bool:
+    if command in GUI_AGENTS and args in (["--help"], ["-h"]):
+        return True
+    options = args[: args.index("--")] if "--" in args else args
+    return command in CLI_AGENTS and any(is_help_option(command, arg) for arg in options)
+
+
+def is_help_option(command: str, arg: str) -> bool:
+    return arg in ("--help", "-h", "--version", "-V") or (
+        arg == "-v" and command in ("pi-headroom", "opencode-headroom")
+    )
+
+
+def forward_agent(config: str | None, command: str, args: list[str]) -> int:
+    if command in GUI_AGENTS:
+        print_gui_help(command)
+        return 0
+    cfg = merge_config(read_config(config))
+    if command == "opencode-headroom":
+        binary = executable(cfg["opencodeExecutable"], "HEADROOM_OPENCODE_EXECUTABLE")
+        return run_agent([binary, *args])
+    binary = preflight(cfg, command, args)
+    if not isinstance(binary, str):
+        raise KitError("The agent executable could not be resolved.")
+    return run_agent([binary, *args])
+
+
+def print_version() -> int:
+    print(f"headroom-kit {distribution_version('headroom-kit')}")
+    print(f"headroom-ai {distribution_version('headroom-ai')}")
+    return 0
+
+
+def distribution_version(name: str) -> str:
+    try:
+        return importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return "not installed"
+
+
+def print_help() -> None:
+    print(
+        """Usage:
+  headroom-kit [--config PATH] run <agent> -- <agent arguments...>
+  headroom-kit copilot-auth login
+  headroom-kit copilot-auth status
+  headroom-kit status
+  headroom-kit stop <port>
+  headroom-kit --help
+  headroom-kit --version
+
+Agents: codex, codex-app, copilot, copilot-vscode, pi, opencode.
+
+--config is a JSON object of non-secret integration defaults. HEADROOM_*
+environment variables override the file, which overrides built-in defaults.
+HEADROOM_VERSION and runtime-selection settings are rejected.
+
+copilot-auth runs Headroom's Copilot login in this install. It does not
+replace the headroom command and does not need a separate Headroom install.
+status and stop do not need provider credentials or model downloads."""
+    )
+
+
+def print_run_help() -> None:
+    print("Usage: headroom-kit [--config PATH] run <agent> -- <agent arguments...>")
+    print("Agents: " + ", ".join(AGENTS))
+    print("Agent help skips the proxy: headroom-kit run codex -- --help")
+
+
+def print_gui_help(command: str) -> None:
+    if command == "copilot-vscode-headroom":
+        print("Usage: headroom-kit run copilot-vscode -- [path]")
+    else:
+        print("Usage: headroom-kit run codex-app --")
+    print("Launch with a shared local Headroom proxy. Use headroom-kit status/stop to manage it.")
+    print(
+        "Normal Codex and VS Code launches keep their existing settings. "
+        "Configure through HEADROOM_*."
+    )

headroom_kit/copilot.py

@@ -0,0 +1,156 @@
+"""Adapt Headroom's TLS and subscription auth without changing its installed files."""
+
+import contextlib
+import os
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Iterator
+from dataclasses import dataclass
+from http.client import HTTPException, HTTPResponse
+from types import ModuleType
+
+from headroom_kit.runtime import KitError
+
+LOGIN_COMMAND = "headroom-kit copilot-auth login"
+
+
+@dataclass(frozen=True)
+class CopilotAuth:
+    api_url: str
+    refresh_oauth_token: str | None
+
+
+def configure_urllib_tls() -> None:
+    from headroom.proxy import ssl_context
+
+    def build_context() -> ssl.SSLContext | None:
+        # Headroom 0.37.0 shares httpx's ALPN list with urllib, which cannot speak h2.
+        context = ssl_context.build_httpx_verify()
+        if isinstance(context, ssl.SSLContext):
+            context.set_alpn_protocols(["http/1.1"])
+            return context
+        return None
+
+    ssl_context.build_urlopen_context = build_context
+
+
+def run_copilot_auth(args: list[str]) -> int:
+    """Run Headroom's Copilot auth in this interpreter."""
+    configure_urllib_tls()
+    try:
+        from click import ClickException
+        from headroom.cli.copilot_auth import copilot_auth
+    except ImportError:
+        raise KitError(
+            "This Headroom release lacks the required Copilot subscription API. "
+            "Install headroom-ai 0.37.0 in this environment."
+        ) from None
+    try:
+        code = copilot_auth.main(
+            args=args,
+            prog_name="headroom-kit copilot-auth",
+            standalone_mode=False,
+        )
+    except ClickException as exc:
+        exc.show()
+        return exc.exit_code
+    return 0 if code is None else int(code)
+
+
+@contextlib.contextmanager
+def auth_failures(adapter: ModuleType) -> Iterator[set[str]]:
+    upstream_urlopen = adapter._urlopen
+    failures: set[str] = set()
+
+    @contextlib.contextmanager
+    def urlopen(request: urllib.request.Request, *, timeout: float) -> Iterator[HTTPResponse]:
+        try:
+            with upstream_urlopen(request, timeout=timeout) as response:
+                yield response
+        except urllib.error.HTTPError as error:
+            if error.code not in (401, 403):
+                failures.add("service")
+            error.close()
+            # Upstream catches and logs exchange failures, including response bodies.
+            raise OSError("Copilot authorization HTTP request failed.") from None
+        except (OSError, HTTPException):
+            failures.add("transport")
+            raise OSError("Copilot authorization transport failed.") from None
+
+    adapter._urlopen = urlopen
+    try:
+        yield failures
+    finally:
+        adapter._urlopen = upstream_urlopen
+
+
+def copilot_auth() -> CopilotAuth:
+    # No upstream wrapper lifecycle: it can restart proxies or edit normal config.
+    try:
+        from headroom import copilot_auth as adapter
+
+        configure_urllib_tls()
+    except ImportError:
+        raise KitError(
+            "This Headroom release lacks the required Copilot subscription API. "
+            "Install headroom-ai 0.37.0 in this environment."
+        ) from None
+    try:
+        with (
+            auth_failures(adapter) as failures,
+            open(os.devnull, "w") as sink,
+            contextlib.redirect_stdout(sink),
+            contextlib.redirect_stderr(sink),
+        ):
+            resolution = adapter.resolve_subscription_bearer_token_details()
+        if resolution is None:
+            if failures:
+                failure = "transport" if "transport" in failures else "service"
+                raise KitError(
+                    f"Copilot authorization {failure} failed. "
+                    "Check network, proxy, CA settings, and GitHub service availability; retry. "
+                    "This does not establish that your saved credentials were rejected."
+                )
+            raise ValueError
+        parsed = urllib.parse.urlsplit(resolution.api_url)
+        if (
+            parsed.scheme != "https"
+            or not (parsed.hostname or "").endswith(".githubcopilot.com")
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError
+        if not resolution.refresh_oauth_token:
+            raise ValueError
+        # Pin the reusable credential, not a rotating access token.
+        return CopilotAuth(
+            api_url=resolution.api_url,
+            refresh_oauth_token=resolution.refresh_oauth_token,
+        )
+    except (AttributeError, OSError, RuntimeError, TypeError, ValueError):
+        raise KitError(
+            "Copilot subscription authorization failed or its endpoint is unsupported. "
+            f"Run `{LOGIN_COMMAND}`, check your subscription, and retry. "
+            "Shared proxies require reusable OAuth and HTTPS *.githubcopilot.com upstreams."
+        ) from None
+
+
+def managed_copilot_auth() -> None:
+    from headroom import copilot_auth as adapter
+
+    configure_urllib_tls()
+    upstream_auth = adapter.apply_copilot_api_auth
+
+    async def authenticate(headers: dict[str, str], *, url: str) -> dict[str, str]:
+        # CLI placeholders and editor tokens both use this proxy's pinned account.
+        if adapter.is_copilot_upstream_url(url):
+            headers = {
+                k: v for k, v in headers.items() if k.lower() not in ("authorization", "x-api-key")
+            }
+        return await upstream_auth(headers, url=url)
+
+    adapter.apply_copilot_api_auth = authenticate