agentgov-cli 0.1.1__tar.gz → 0.1.3__tar.gz

{agentgov_cli-0.1.1 → agentgov_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgov-cli
-Version: 0.1.1
+Version: 0.1.3
 Summary: AgentGov CLI — wrap Claude Code, bind work items, check gateway health.
 Author: AgentGov Contributors
 License: Apache-2.0

agentgov_cli-0.1.3/agentgov_cli/commands/gateway.py

@@ -0,0 +1,79 @@
+"""`agentgov gateway` — manage the local gateway process.
+
+`install` is the recommended path: a supervised service (systemd --user on
+Linux/WSL, launchd on macOS) that starts at login and restarts on failure, so
+the port Claude Code targets is bound whenever the developer is working.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from .. import gateway_process as gp
+
+console = Console()
+
+app = typer.Typer(name="gateway", help="Manage the local AgentGov gateway process.")
+
+_GATEWAY_OPT = typer.Option(None, "--gateway", envvar="AGENTGOV_GATEWAY_URL")
+
+
+def _url(gateway_url: str | None) -> str:
+    return gateway_url or "http://localhost:8000"
+
+
+@app.command("install")
+def install(gateway_url: str = _GATEWAY_OPT) -> None:
+    """Install + start the gateway as a supervised background service."""
+    url = _url(gateway_url)
+    ok, detail = gp.install_service()
+    if not ok:
+        console.print(f"[yellow]Could not install a service:[/] {detail}")
+        console.print("Falling back to a detached one-off start.")
+        ok, detail = gp.ensure_running(url)
+        if not ok:
+            console.print(f"[red]Gateway did not start.[/] {detail}")
+            raise typer.Exit(1)
+        console.print(f"[green]Gateway running[/] at {url} ({detail})")
+        return
+
+    console.print(f"[green]{detail}[/]")
+    if gp.is_healthy(url, timeout_sec=10.0):
+        console.print(f"[green]Gateway healthy[/] at {url}")
+    else:
+        # The service manager accepted the unit but the process is not
+        # answering — surface the log rather than claiming success.
+        console.print(f"[yellow]Service installed but {url}/health did not answer yet.[/]")
+        console.print(gp.log_tail())
+        raise typer.Exit(1)
+
+
+@app.command("start")
+def start(gateway_url: str = _GATEWAY_OPT) -> None:
+    """Start the gateway now, detached from this terminal."""
+    url = _url(gateway_url)
+    ok, detail = gp.ensure_running(url)
+    if not ok:
+        console.print(f"[red]Gateway did not start.[/] {detail}")
+        raise typer.Exit(1)
+    console.print(f"[green]Gateway running[/] at {url} ({detail})")
+
+
+@app.command("status")
+def status(gateway_url: str = _GATEWAY_OPT) -> None:
+    """Report whether the gateway is answering."""
+    url = _url(gateway_url)
+    if gp.is_healthy(url):
+        console.print(f"[green]RUNNING[/] — {url}/health answered.")
+        return
+    console.print(f"[red]NOT RUNNING[/] — nothing answering at {url}/health.")
+    console.print("Start it with: [cyan]agentgov gateway install[/]")
+    console.print(gp.log_tail())
+    raise typer.Exit(1)
+
+
+@app.command("logs")
+def logs(lines: int = typer.Option(40, "--lines", "-n")) -> None:
+    """Show the tail of the gateway log."""
+    console.print(gp.log_tail(lines))

{agentgov_cli-0.1.1 → agentgov_cli-0.1.3}/agentgov_cli/commands/register_device.py

@@ -57,14 +57,27 @@ def run(
         console.print(f"[red]Invalid --mode {upstream_mode}[/]")
         raise typer.Exit(2)
 
-    tower = tower_url or os.environ.get("CONTROL_TOWER_URL") or "http://localhost:3000"
-
     identity_path = Path.home() / ".agentgov" / "identity.json"
     if not identity_path.exists():
         console.print("[red]No AgentGov identity found.[/] Run [bold]agentgov login[/] first.")
         raise typer.Exit(2)
     identity = json.loads(identity_path.read_text())
     token = identity.get("auth0_token") or ""
+
+    # Tower URL precedence: explicit --tower > CONTROL_TOWER_URL env >
+    # the tower we logged in against (identity.json) > localhost dev default.
+    #
+    # The identity.json fallback matters: `agentgov login --tower https://...`
+    # persists the tower, but a NEW shell won't have CONTROL_TOWER_URL set.
+    # Without this fallback register-device silently tried localhost:3000 and
+    # died with "Connection refused" even though login had just succeeded.
+    tower = (
+        tower_url
+        or os.environ.get("CONTROL_TOWER_URL")
+        or identity.get("tower_url")
+        or "http://localhost:3000"
+    )
+    console.print(f"[dim]Registering against control tower:[/] {tower}")
     if not token:
         console.print("[red]Identity file is missing auth0_token.[/] Re-run `agentgov login`.")
         raise typer.Exit(2)
@@ -110,16 +123,24 @@ def run(
     device = payload.get("device", {})
     gtw_token = payload.get("gateway_service_token") or ""
 
-    # Persist gateway creds.
+    # Persist a COMPLETE gateway config so `agentgov-gateway` boots with zero
+    # environment variables. config.py reads this file when the corresponding
+    # env vars are absent; env still wins if explicitly set.
     creds_path = Path.home() / ".agentgov" / "gateway_creds.json"
     creds_path.write_text(
         json.dumps(
             {
                 "tower_url": tower,
+                "control_tower_url": tower,
                 "device_id": device.get("id"),
                 "device_name": device.get("name"),
-                "upstream_mode": device.get("upstream_mode"),
+                "upstream_mode": device.get("upstream_mode") or upstream_mode,
                 "gateway_service_token": gtw_token,
+                # Public verify-only key; the tower returns it at registration.
+                "policy_signing_public_key_b64": payload.get(
+                    "policy_signing_public_key_b64", ""
+                ),
+                "device_key_path": str(priv_path),
             },
             indent=2,
         )
@@ -129,9 +150,7 @@ def run(
     console.print(
         f"[green]✅ Device registered.[/] id={device.get('id')} mode={device.get('upstream_mode')}"
     )
-    console.print(f"gateway_service_token saved to {creds_path}")
+    console.print(f"Gateway config saved to {creds_path}")
     console.print()
-    console.print("Now start (or restart) the gateway with these env vars — see .env:")
-    console.print(f"  GATEWAY_SERVICE_TOKEN={gtw_token}")
-    console.print(f"  DEVICE_KEY_PATH={priv_path}")
-    console.print(f"  UPSTREAM_MODE={upstream_mode}")
+    console.print("[bold]Start the gateway — no environment variables needed:[/]")
+    console.print("  agentgov-gateway")

{agentgov_cli-0.1.1 → agentgov_cli-0.1.3}/agentgov_cli/commands/wrap.py

@@ -78,6 +78,13 @@ def run(
     target = list(cmd) if cmd else ["claude"]
     gateway = gateway_url or "http://localhost:8000"
 
+    # Never hand Claude Code a dead base URL. We are about to set
+    # ANTHROPIC_BASE_URL=<gateway>; if nothing is listening there, Claude Code
+    # fails with an opaque "API Error: Connection refused" from inside its own
+    # request path, with no mention of AgentGov. Verify first, and start a
+    # local gateway on demand.
+    _require_gateway(gateway)
+
     # Register the session with the gateway. Also send hook hashes so the
     # gateway can compare against expected values from the signed snapshot
     # (gap-P0-4 hook integrity check). Mismatch = warning + audit row;
@@ -130,6 +137,57 @@ def _wait_for_port(listener: LoopbackListener, timeout_sec: float = 2.0) -> None
         _time.sleep(0.01)
 
 
+def _is_loopback(gateway: str) -> bool:
+    """True if `gateway` points at this machine (so we may start it ourselves)."""
+    from urllib.parse import urlparse
+
+    host = (urlparse(gateway).hostname or "").lower()
+    return host in {"localhost", "127.0.0.1", "::1", "0.0.0.0"}
+
+
+def _require_gateway(gateway: str) -> None:
+    """Ensure a healthy gateway at `gateway`, or exit with actionable guidance.
+
+    Local gateways are started on demand (detached, so they outlive this
+    terminal). Remote gateways (§12 enterprise-remote) are never started by us —
+    we only report that they are unreachable.
+    """
+    from .. import gateway_process as gp
+
+    if gp.is_healthy(gateway):
+        return
+
+    if not _is_loopback(gateway):
+        console.print(
+            f"[red]AgentGov gateway at {gateway} is not reachable.[/]\n"
+            "This is a remote gateway, so this machine cannot start it. "
+            "Check the URL and your network, or contact your administrator."
+        )
+        raise typer.Exit(2)
+
+    console.print(f"[yellow]Gateway not running at {gateway} — starting it...[/]")
+    ok, detail = gp.start_detached(gateway)
+    if ok:
+        console.print(f"[green]Gateway started.[/] {detail}")
+        console.print(
+            "Tip: run [cyan]agentgov gateway install[/] once to have it start "
+            "automatically at login and restart on failure."
+        )
+        return
+
+    # Refuse to launch rather than hand Claude Code a dead URL.
+    console.print(f"[red]Could not start the AgentGov gateway at {gateway}.[/]\n{detail}")
+    console.print(
+        "\nClaude Code was NOT launched, because it would have failed with an "
+        "opaque connection error.\n"
+        "Fix the gateway, then retry:\n"
+        "  [cyan]agentgov gateway install[/]   # install as a supervised service\n"
+        "  [cyan]agentgov gateway logs[/]      # see why it is failing\n"
+        "  [cyan]agentgov doctor[/]            # full diagnosis"
+    )
+    raise typer.Exit(2)
+
+
 def _resolve_repo() -> tuple[Path, str]:
     try:
         root = subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()

agentgov_cli-0.1.3/agentgov_cli/gateway_process.py

@@ -0,0 +1,261 @@
+"""Local gateway process lifecycle.
+
+Why this module exists
+----------------------
+`agentgov wrap` points Claude Code's ANTHROPIC_BASE_URL at the local gateway.
+If nothing is listening on that port, Claude Code fails with a bare
+``API Error: Connection refused`` from deep inside its own request path —
+typically mid-compaction, with no mention of AgentGov. Users reasonably
+conclude the governance layer is broken and reach for the uninstall recipe.
+
+The old setup instructions made that outcome likely: the gateway was started as
+a bare ``agentgov-gateway &`` job of an interactive shell, so it received
+SIGHUP and died as soon as that terminal closed. Combined with a machine-wide
+``managed-settings.json`` forcing ANTHROPIC_BASE_URL, one closed terminal
+bricked *every* Claude Code session on the machine.
+
+So: never hand Claude Code a dead base URL. Callers use `ensure_running()`,
+which probes /health, starts a detached gateway if needed, and reports honestly
+if it could not.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+# Where a detached gateway writes its log. Kept next to the rest of the
+# per-user state so `agentgov doctor` and the support bundle can find it.
+AGENTGOV_HOME = Path.home() / ".agentgov"
+GATEWAY_LOG = AGENTGOV_HOME / "gateway.log"
+
+# Health probe budget. The gateway binds its port before the lifespan's first
+# control-tower call, so a healthy boot answers well inside this.
+_BOOT_TIMEOUT_SEC = 20.0
+_POLL_INTERVAL_SEC = 0.25
+
+
+def is_healthy(gateway_url: str, timeout_sec: float = 2.0) -> bool:
+    """True if a gateway answers /health at `gateway_url`."""
+    try:
+        r = httpx.get(f"{gateway_url.rstrip('/')}/health", timeout=timeout_sec)
+    except httpx.HTTPError:
+        return False
+    return r.status_code == 200
+
+
+def find_executable() -> str | None:
+    """Locate the `agentgov-gateway` entry point.
+
+    Checked in order:
+      1. The same directory as the running `agentgov` CLI. This is the common
+         case — the setup instructions install both packages into the single
+         venv at ~/.agentgov/venv, so the gateway is our sibling even when that
+         venv is not on PATH (a fresh shell that never sourced the rc file).
+      2. PATH.
+    """
+    sibling = Path(sys.argv[0]).resolve().parent / "agentgov-gateway"
+    if sibling.is_file() and os.access(sibling, os.X_OK):
+        return str(sibling)
+
+    from shutil import which
+
+    return which("agentgov-gateway")
+
+
+def start_detached(gateway_url: str) -> tuple[bool, str]:
+    """Start the gateway fully detached from this terminal.
+
+    Returns (healthy, detail). Detached means it survives the parent shell:
+    a new session (setsid) so the terminal's SIGHUP on close never reaches it,
+    and stdio redirected to the log file rather than the inherited tty.
+    """
+    exe = find_executable()
+    if exe is None:
+        return False, (
+            "could not find the `agentgov-gateway` executable. Install it with:\n"
+            "  ~/.agentgov/venv/bin/pip install --upgrade agentgov-gateway"
+        )
+
+    AGENTGOV_HOME.mkdir(parents=True, exist_ok=True)
+    try:
+        log_fh = GATEWAY_LOG.open("ab")
+    except OSError as e:
+        return False, f"could not open {GATEWAY_LOG}: {e}"
+
+    try:
+        # start_new_session=True == setsid(): the child leads its own process
+        # group and session, so closing this terminal does not signal it.
+        subprocess.Popen(
+            [exe],
+            stdin=subprocess.DEVNULL,
+            stdout=log_fh,
+            stderr=log_fh,
+            start_new_session=True,
+            # Run from home, not the caller's cwd: the gateway resolves its
+            # default .runtime/ paths relative to cwd, and we do not want a
+            # stray .runtime/ directory inside whatever repo the developer
+            # happened to launch from.
+            cwd=str(Path.home()),
+        )
+    except OSError as e:
+        return False, f"could not start {exe}: {e}"
+    finally:
+        log_fh.close()
+
+    deadline = time.time() + _BOOT_TIMEOUT_SEC
+    while time.time() < deadline:
+        if is_healthy(gateway_url, timeout_sec=1.0):
+            return True, f"started; logging to {GATEWAY_LOG}"
+        time.sleep(_POLL_INTERVAL_SEC)
+
+    return False, (
+        f"started but did not answer /health within {int(_BOOT_TIMEOUT_SEC)}s.\n"
+        f"{log_tail()}"
+    )
+
+
+def ensure_running(gateway_url: str) -> tuple[bool, str]:
+    """Guarantee a healthy gateway at `gateway_url`, starting one if needed.
+
+    Returns (healthy, detail). Callers MUST NOT launch Claude Code when this
+    returns False — a dead base URL surfaces as an opaque connection error.
+    """
+    if is_healthy(gateway_url):
+        return True, "already running"
+    return start_detached(gateway_url)
+
+
+def log_tail(lines: int = 15) -> str:
+    """Last `lines` of the gateway log, formatted for terminal display."""
+    if not GATEWAY_LOG.exists():
+        return f"(no log at {GATEWAY_LOG})"
+    try:
+        content = GATEWAY_LOG.read_text(errors="replace").splitlines()
+    except OSError as e:
+        return f"(could not read {GATEWAY_LOG}: {e})"
+    tail = content[-lines:]
+    body = "\n".join(f"  {ln}" for ln in tail)
+    return f"Last {len(tail)} line(s) of {GATEWAY_LOG}:\n{body}"
+
+
+# ---------------------------------------------------------------------------
+# Service installation
+#
+# A supervised service is the real fix for "my gateway died": it starts at
+# login and restarts on crash, so the port is bound whenever the developer is
+# using their machine. `ensure_running` is the belt to this pair of braces.
+# ---------------------------------------------------------------------------
+
+SYSTEMD_UNIT_PATH = Path.home() / ".config" / "systemd" / "user" / "agentgov-gateway.service"
+LAUNCHD_PLIST_PATH = Path.home() / "Library" / "LaunchAgents" / "ai.agentgov.gateway.plist"
+
+
+def _systemd_unit(exe: str) -> str:
+    return f"""[Unit]
+Description=AgentGov local governance gateway
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart={exe}
+WorkingDirectory=%h
+Restart=always
+RestartSec=3
+StandardOutput=append:%h/.agentgov/gateway.log
+StandardError=append:%h/.agentgov/gateway.log
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _launchd_plist(exe: str) -> str:
+    log = str(GATEWAY_LOG)
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>            <string>ai.agentgov.gateway</string>
+    <key>ProgramArguments</key> <array><string>{exe}</string></array>
+    <key>RunAtLoad</key>        <true/>
+    <key>KeepAlive</key>        <true/>
+    <key>WorkingDirectory</key> <string>{Path.home()}</string>
+    <key>StandardOutPath</key>  <string>{log}</string>
+    <key>StandardErrorPath</key><string>{log}</string>
+</dict>
+</plist>
+"""
+
+
+def install_service() -> tuple[bool, str]:
+    """Install + start a supervised gateway service for the current user.
+
+    systemd --user on Linux/WSL, launchd on macOS. Returns (ok, detail).
+    """
+    exe = find_executable()
+    if exe is None:
+        return False, (
+            "could not find the `agentgov-gateway` executable. Install it with:\n"
+            "  ~/.agentgov/venv/bin/pip install --upgrade agentgov-gateway"
+        )
+    AGENTGOV_HOME.mkdir(parents=True, exist_ok=True)
+    system = platform.system()
+
+    if system == "Darwin":
+        LAUNCHD_PLIST_PATH.parent.mkdir(parents=True, exist_ok=True)
+        LAUNCHD_PLIST_PATH.write_text(_launchd_plist(exe))
+        # `bootout` first so a re-install picks up an edited plist. It fails
+        # harmlessly when nothing is loaded, hence check=False.
+        uid = os.getuid()
+        subprocess.run(
+            ["launchctl", "bootout", f"gui/{uid}/ai.agentgov.gateway"],
+            check=False,
+            capture_output=True,
+        )
+        r = subprocess.run(
+            ["launchctl", "bootstrap", f"gui/{uid}", str(LAUNCHD_PLIST_PATH)],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if r.returncode != 0:
+            return False, f"launchctl bootstrap failed: {r.stderr.strip() or r.returncode}"
+        return True, f"launchd agent installed at {LAUNCHD_PLIST_PATH}"
+
+    if system == "Linux":
+        from shutil import which
+
+        if which("systemctl") is None:
+            return False, (
+                "systemctl not found. This environment has no systemd user session "
+                "(common on minimal WSL setups).\n"
+                "The gateway will still be auto-started on demand by `agentgov wrap`."
+            )
+        SYSTEMD_UNIT_PATH.parent.mkdir(parents=True, exist_ok=True)
+        SYSTEMD_UNIT_PATH.write_text(_systemd_unit(exe))
+        subprocess.run(["systemctl", "--user", "daemon-reload"], check=False, capture_output=True)
+        r = subprocess.run(
+            ["systemctl", "--user", "enable", "--now", "agentgov-gateway"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if r.returncode != 0:
+            return False, (
+                f"systemctl --user enable --now failed: {r.stderr.strip() or r.returncode}\n"
+                "On WSL without systemd, `agentgov wrap` will auto-start the gateway instead."
+            )
+        return True, f"systemd user unit installed at {SYSTEMD_UNIT_PATH}"
+
+    return False, (
+        f"no service manager integration for {system}. "
+        "`agentgov wrap` will auto-start the gateway on demand."
+    )

{agentgov_cli-0.1.1 → agentgov_cli-0.1.3}/agentgov_cli/main.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import typer
 
-from .commands import doctor, install, login, register_device, status, workitem, wrap
+from .commands import doctor, gateway, install, login, register_device, status, workitem, wrap
 
 app = typer.Typer(
     name="agentgov",
@@ -19,6 +19,7 @@ app.command(
 app.command(
     "install", help="Install client assets into ~/.claude/ and print managed-settings.json."
 )(install.run)
+app.add_typer(gateway.app, name="gateway")
 app.command("wrap", help="Wrap `claude` — start a governed Claude Code session.")(wrap.run)
 app.command("workitem", help="Bind the current session to a work item (JIRA/Notion/PRJ-...).")(
     workitem.run

{agentgov_cli-0.1.1 → agentgov_cli-0.1.3}/pyproject.toml

@@ -2,7 +2,7 @@
 # PyPI: `agentgov` was rejected as too similar to existing `agent-gov`.
 # Package name is agentgov-cli; the console command it installs is still `agentgov`.
 name = "agentgov-cli"
-version = "0.1.1"
+version = "0.1.3"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }