ags-cli 0.1.0__py3-none-any.whl

cli/commands/run.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+
+app = typer.Typer(help="Start runs and compare/merge outputs.")
+console = Console()
+
+
+@app.command("start")
+def start(
+    objective: str = typer.Option(None, "--objective", "-o"),
+    task_id: str = typer.Option(None, "--task"),
+    workspace: str = typer.Option("default", "--workspace", "-w"),
+    policy: str = typer.Option("single", "--policy", "-p", help="Routing policy name."),
+    providers: str = typer.Option(
+        None, "--providers", help="Comma-separated provider override, e.g. mock,local."
+    ),
+    model: str = typer.Option(None, "--model", "-m", help="One-off model override for this run."),
+    inline: bool = typer.Option(
+        False, "--inline", help="Run synchronously in the API (no worker needed)."
+    ),
+    follow: bool = typer.Option(False, "--follow", "-f", help="Tail the first run live."),
+) -> None:
+    """Start a run for an objective or existing task."""
+    client = HarnessClient()
+    body = {
+        "objective": objective,
+        "task_id": task_id,
+        "workspace": workspace,
+        "policy": policy,
+        "providers": providers.split(",") if providers else None,
+        "model": model,
+    }
+    data = client.post("/runs/start", json=body, inline=inline)
+    console.print(f"[green]session[/green] {data['session_id']}  dispatched={data['dispatched']}")
+    table = Table("run_id", "provider", "role", "status")
+    for r in data["runs"]:
+        table.add_row(r["id"], r["adapter_kind"], r["role"], r["status"])
+    console.print(table)
+
+    if follow and data["runs"]:
+        run_id = data["runs"][0]["id"]
+        console.print(f"[dim]— streaming run {run_id} —[/dim]")
+        for frame in client.stream(run_id):
+            try:
+                ev = json.loads(frame)
+            except json.JSONDecodeError:
+                continue
+            if ev.get("type") == "token":
+                console.print(ev.get("text", ""), end="")
+            elif ev.get("type") == "status":
+                console.print(f"\n[cyan][{ev.get('status')}][/cyan]")
+
+
+@app.command("compare")
+def compare(
+    run_ids: str = typer.Argument(..., help="Comma-separated run ids."),
+    strategy: str = typer.Option("judge", "--strategy", "-s"),
+) -> None:
+    """Compare two or more runs side by side."""
+    client = HarnessClient()
+    data = client.post(
+        "/runs/compare", json={"run_ids": run_ids.split(","), "strategy": strategy}
+    )
+    console.print_json(data=data["result"])
+
+
+@app.command("merge")
+def merge(
+    run_ids: str = typer.Argument(...),
+    persist: bool = typer.Option(True, "--persist/--no-persist"),
+) -> None:
+    """Merge runs into a canonical answer (optionally persisted as memory)."""
+    client = HarnessClient()
+    data = client.post("/runs/merge", json={"run_ids": run_ids.split(","), "persist": persist})
+    console.print(data["result"].get("merged_content", ""))
+    if data.get("canonical_memory_item_id"):
+        console.print(f"\n[green]persisted as memory[/green] {data['canonical_memory_item_id']}")

cli/commands/serve.py

@@ -0,0 +1,171 @@
+"""``ags serve`` — run the daemonless server (API + in-process worker).
+
+A uvicorn server backed by SQLite, with run execution happening in-process.
+The CLI auto-spawns this on first use; you can also run it in the foreground for logs."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+
+import typer
+
+
+def _uvicorn_log_config(log_file) -> dict | None:
+    """A uvicorn logging config that also writes to ``~/.ags/server.log``.
+
+    When the server runs as the Tauri sidecar, its stdout/stderr go to the (hidden)
+    desktop-app process and are invisible on Windows — a startup crash (e.g. a failed
+    ASGI import) then shows up only as a perpetually-loading GUI. Feeding uvicorn a
+    log config with an extra file handler means those errors land in a file the user
+    can open and send us. Built from uvicorn's own defaults so console output is
+    unchanged. Best-effort: returns None if uvicorn's config can't be read."""
+    try:
+        import copy
+
+        from uvicorn.config import LOGGING_CONFIG
+
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        cfg = copy.deepcopy(LOGGING_CONFIG)
+        cfg.setdefault("formatters", {})["plainfile"] = {
+            "format": "%(asctime)s %(levelname)s %(name)s: %(message)s",
+        }
+        cfg.setdefault("handlers", {})["logfile"] = {
+            "class": "logging.FileHandler",
+            "filename": str(log_file),
+            "formatter": "plainfile",
+            "encoding": "utf-8",
+        }
+        # uvicorn.error propagates to the "uvicorn" logger, so adding the file handler
+        # there (plus access) captures startup/runtime errors without duplication.
+        for name in ("uvicorn", "uvicorn.access"):
+            lg = cfg.setdefault("loggers", {}).setdefault(name, {})
+            lg["handlers"] = list(dict.fromkeys([*lg.get("handlers", []), "logfile"]))
+        return cfg
+    except Exception:  # noqa: BLE001  (diagnostics only — never fail startup)
+        return None
+
+# Default bind address. Loopback-only unless HARNESS_API_HOST is set (e.g. 0.0.0.0 to
+# expose the GUI/API to the LAN). Reading the env here means the auto-spawned server
+# (from `ags gui`) inherits it too — `HARNESS_API_HOST=0.0.0.0 ags gui` binds the LAN.
+_DEFAULT_HOST = os.environ.get("HARNESS_API_HOST", "127.0.0.1")
+
+# Explicit acknowledgement required to bind a non-loopback address. The API has no auth
+# and exposes destructive, project-scoped file operations (write/create/rename/delete),
+# so binding it to the LAN hands any host on the network unauthenticated write access to
+# the project folder. Loopback is enforced unless the operator opts in on purpose.
+_INSECURE_BIND_ENV = "HARNESS_ALLOW_INSECURE_BIND"
+
+
+def _is_loopback(host: str) -> bool:
+    """True when ``host`` binds only the local machine. Covers the literal loopback
+    addresses, the ``127.0.0.0/8`` range, and the ``localhost`` hostname. Anything
+    else (``0.0.0.0``, ``::``, a routable IP/name) is treated as non-loopback."""
+    import ipaddress
+
+    h = host.strip().strip("[]").lower()  # tolerate bracketed IPv6
+    if h in ("localhost", "localhost.localdomain"):
+        return True
+    try:
+        return ipaddress.ip_address(h).is_loopback
+    except ValueError:
+        return False
+
+
+def _log_startup_crash(log_file) -> None:
+    """Best-effort plain-file crash log for a failure BEFORE uvicorn's own logging is
+    configured — e.g. an import-time crash on ``from harness.main import app``, which
+    happens before ``uvicorn.run()`` is even called, so ``_uvicorn_log_config``'s file
+    handler (wired up inside uvicorn's own config) never gets installed. As the Tauri
+    sidecar this process has no console at all (release builds are windowed —
+    ``windows_subsystem = "windows"``), so without this, an uncaught exception here
+    vanishes with zero trace and the GUI just sees a perpetually-loading API. Deliberately
+    plain file I/O, not the logging module — that's exactly what might not be set up yet."""
+    import traceback
+
+    with contextlib.suppress(Exception):
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write("\n--- ags serve crashed at startup ---\n")
+            f.write(traceback.format_exc())
+
+
+def _force_utf8_streams() -> None:
+    """Reconfigure stdout/stderr to UTF-8 so Unicode output can't crash the process.
+
+    When the Tauri sidecar spawns ``ags serve`` its stdout/stderr are pipes, not a
+    console — so on Windows Python defaults them to the legacy ``cp1252`` (``charmap``)
+    codec, which can't encode common non-ASCII characters. A single Unicode char in a
+    log line (or the startup banner) then raises ``UnicodeEncodeError`` and kills the
+    whole server before uvicorn even binds — the GUI only sees a dead backend. This
+    ran fine when launched manually because a real terminal uses a capable codepage.
+    ``errors='replace'`` is belt-and-suspenders so nothing downstream can ever throw."""
+    import sys
+
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            with contextlib.suppress(Exception):
+                reconfigure(encoding="utf-8", errors="replace")
+
+
+def _run_uvicorn(host: str, port: int, log_file) -> None:
+    import uvicorn
+
+    log_config = _uvicorn_log_config(log_file)
+    # Import the ASGI app and hand uvicorn the OBJECT, not the "harness.main:app"
+    # import string. In a PyInstaller bundle (the Tauri sidecar), uvicorn's re-import
+    # of that string fails with "Could not import module 'harness.main'" and the
+    # server never binds — which the GUI only sees as a perpetually-loading API. A
+    # single-worker, no-reload server doesn't need the import string, so passing the
+    # object works identically from source and frozen.
+    from harness.main import app as asgi_app
+
+    uvicorn.run(asgi_app, host=host, port=port, log_level="warning",
+                **({"log_config": log_config} if log_config else {}))
+
+
+def serve(
+    host: str = typer.Option(
+        _DEFAULT_HOST, "--host",
+        help=f"Bind address. Loopback only unless {_INSECURE_BIND_ENV}=1 is set.",
+    ),
+    port: int = typer.Option(8770, "--port", "-p", help="Bind port."),
+) -> None:
+    """Start the local AgentS server in the foreground."""
+    _force_utf8_streams()  # must run before any output — see the helper's docstring
+
+    # Refuse to expose the unauthenticated, file-mutating API beyond this machine unless
+    # the operator has explicitly acknowledged the risk. Keeps `ags serve` and the
+    # auto-spawned GUI sidecar safe-by-default while preserving a deliberate LAN opt-in.
+    if not _is_loopback(host) and os.environ.get(_INSECURE_BIND_ENV) not in ("1", "true", "yes"):
+        with contextlib.suppress(Exception):
+            print(
+                f"Refusing to bind non-loopback host {host!r}: the AgentS API has no "
+                f"authentication and can read/write/delete files in the project folder. "
+                f"Set {_INSECURE_BIND_ENV}=1 to override (only on a trusted network).",
+                flush=True,
+            )
+        raise typer.Exit(2)
+
+    from cli.local import LOG_FILE, PID_FILE, _write_api_url
+
+    base_url = f"http://localhost:{port}"
+    PID_FILE.parent.mkdir(parents=True, exist_ok=True)
+    PID_FILE.write_text(str(os.getpid()))
+    _write_api_url(base_url)  # record so `ags` in any terminal finds this server
+
+    # Plain ASCII banner via print(), not the rich Console: rich caches the stream's
+    # (legacy cp1252) encoding at construction — before _force_utf8_streams runs — and
+    # its legacy-Windows renderer would still choke on a non-ASCII glyph like the old
+    # "▶". ASCII text through a UTF-8 stream can't raise; wrapped anyway for safety.
+    with contextlib.suppress(Exception):
+        print(f"AgentS (local) serving on {base_url}  (Ctrl-C to stop)", flush=True)
+    try:
+        _run_uvicorn(host, port, LOG_FILE)
+    except Exception:
+        _log_startup_crash(LOG_FILE)
+        raise
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            PID_FILE.unlink()

cli/commands/service.py

@@ -0,0 +1,236 @@
+"""`ags service install` and `ags service uninstall` — supervised local server.
+
+Writes systemd user unit (Linux) or launchd plist (macOS) to auto-start the
+server on login. Idempotent; refuses to overwrite a file it didn't create.
+
+    ags service install   # write ~/.config/systemd/user/ags.service (Linux)
+                          # or ~/Library/LaunchAgents/com.ags.serve.plist (macOS)
+    ags service uninstall # remove the service unit/plist
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+app = typer.Typer(help="Install or uninstall the local server as a system service.", no_args_is_help=True)
+
+
+@app.callback(invoke_without_command=True)
+def _check_platform(ctx: typer.Context) -> None:
+    """Check platform support on entry; fail early for unsupported platforms."""
+    if not (sys.platform.startswith("linux") or sys.platform == "darwin"):
+        console.print(
+            f"[red]✗ Unsupported platform: {sys.platform}[/red]\n"
+            "[yellow]Only Linux (systemd) and macOS (launchd) are supported.[/yellow]"
+        )
+        raise typer.Exit(1)
+
+# Markers to detect managed files
+_SYSTEMD_MARKER = "# managed by ags"
+_LAUNCHD_MARKER = "<!-- managed by ags -->"
+
+
+def _get_systemd_path() -> Path:
+    """Return the path to the systemd user unit file."""
+    home = Path.home()
+    return home / ".config" / "systemd" / "user" / "ags.service"
+
+
+def _get_launchd_path() -> Path:
+    """Return the path to the launchd plist file."""
+    home = Path.home()
+    return home / "Library" / "LaunchAgents" / "com.ags.serve.plist"
+
+
+def _get_ags_path() -> str | None:
+    """Resolve the ags binary path via shutil.which(); return None if not found."""
+    return shutil.which("ags")
+
+
+def _is_managed_systemd(path: Path) -> bool:
+    """Check if a systemd unit file was created by ags (has the marker)."""
+    if not path.exists():
+        return False
+    try:
+        return _SYSTEMD_MARKER in path.read_text()
+    except Exception:
+        return False
+
+
+def _is_managed_launchd(path: Path) -> bool:
+    """Check if a launchd plist was created by ags (has the marker)."""
+    if not path.exists():
+        return False
+    try:
+        return _LAUNCHD_MARKER in path.read_text()
+    except Exception:
+        return False
+
+
+def _write_systemd_unit(ags_path: str, unit_path: Path) -> None:
+    """Write the systemd user service unit."""
+    unit_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Build the Environment line if HARNESS_API_HOST is set
+    env_line = ""
+    if "HARNESS_API_HOST" in os.environ:
+        env_line = f'Environment="HARNESS_API_HOST={os.environ["HARNESS_API_HOST"]}"\n'
+
+    content = f"""{_SYSTEMD_MARKER}
+[Unit]
+Description=AgentS local server
+
+[Service]
+ExecStart="{ags_path}" serve
+Restart=on-failure
+{env_line}[Install]
+WantedBy=default.target
+"""
+
+    unit_path.write_text(content)
+
+
+def _write_launchd_plist(ags_path: str, plist_path: Path) -> None:
+    """Write the launchd plist."""
+    plist_path.parent.mkdir(parents=True, exist_ok=True)
+
+    plist_content = 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">
+{_LAUNCHD_MARKER}
+<dict>
+    <key>Label</key>
+    <string>com.ags.serve</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{ags_path}</string>
+        <string>serve</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+</dict>
+</plist>
+"""
+
+    plist_path.write_text(plist_content)
+
+
+@app.command("install")
+def install() -> None:
+    """Install the local server as a system service (systemd / launchd)."""
+    ags_path = _get_ags_path()
+    if not ags_path:
+        console.print("[red]✗ ags not found on PATH[/red]")
+        raise typer.Exit(1)
+
+    if sys.platform.startswith("linux"):
+        unit_path = _get_systemd_path()
+
+        # Check if file exists and is not managed by ags
+        was_installed = unit_path.exists() and _is_managed_systemd(unit_path)
+        if unit_path.exists() and not _is_managed_systemd(unit_path):
+            console.print(
+                f"[red]✗ {unit_path} already exists but is not managed by ags.[/red]\n"
+                "[yellow]Remove it or use a different configuration.[/yellow]"
+            )
+            raise typer.Exit(1)
+
+        # Write the unit file
+        _write_systemd_unit(ags_path, unit_path)
+
+        # Print info
+        if was_installed:
+            console.print("[green]✓ Service already installed — refreshed[/green]")
+        else:
+            console.print("[green]✓ Service installed[/green]")
+
+        console.print(
+            "\n[dim]Run this to enable and start the service:[/dim]\n"
+            "[bold]systemctl --user daemon-reload && systemctl --user enable --now ags[/bold]"
+        )
+
+    elif sys.platform == "darwin":
+        plist_path = _get_launchd_path()
+
+        # Check if file exists and is not managed by ags
+        was_installed = plist_path.exists() and _is_managed_launchd(plist_path)
+        if plist_path.exists() and not _is_managed_launchd(plist_path):
+            console.print(
+                f"[red]✗ {plist_path} already exists but is not managed by ags.[/red]\n"
+                "[yellow]Remove it or use a different configuration.[/yellow]"
+            )
+            raise typer.Exit(1)
+
+        # Write the plist
+        _write_launchd_plist(ags_path, plist_path)
+
+        # Print info
+        if was_installed:
+            console.print("[green]✓ Service already installed — refreshed[/green]")
+        else:
+            console.print("[green]✓ Service installed[/green]")
+
+        console.print(
+            "\n[dim]Run this to load the service:[/dim]\n"
+            f"[bold]launchctl bootstrap gui/$(id -u) {plist_path}[/bold]"
+        )
+
+
+
+@app.command("uninstall")
+def uninstall() -> None:
+    """Remove the local server service unit (systemd / launchd)."""
+    if sys.platform.startswith("linux"):
+        unit_path = _get_systemd_path()
+
+        if not unit_path.exists():
+            console.print("[dim]Service not installed[/dim]")
+            raise typer.Exit(0)
+
+        if not _is_managed_systemd(unit_path):
+            console.print(
+                f"[red]✗ {unit_path} exists but is not managed by ags.[/red]\n"
+                "[yellow]Remove it manually if you want to delete it.[/yellow]"
+            )
+            raise typer.Exit(1)
+
+        unit_path.unlink()
+        console.print("[green]✓ Service uninstalled[/green]")
+        console.print(
+            "\n[dim]Run this to disable the service:[/dim]\n"
+            "[bold]systemctl --user daemon-reload && systemctl --user disable ags[/bold]"
+        )
+
+    elif sys.platform == "darwin":
+        plist_path = _get_launchd_path()
+
+        if not plist_path.exists():
+            console.print("[dim]Service not installed[/dim]")
+            raise typer.Exit(0)
+
+        if not _is_managed_launchd(plist_path):
+            console.print(
+                f"[red]✗ {plist_path} exists but is not managed by ags.[/red]\n"
+                "[yellow]Remove it manually if you want to delete it.[/yellow]"
+            )
+            raise typer.Exit(1)
+
+        plist_path.unlink()
+        console.print("[green]✓ Service uninstalled[/green]")
+        console.print(
+            "\n[dim]Run this to unload the service:[/dim]\n"
+            "[bold]launchctl bootout gui/$(id -u)/com.ags.serve[/bold]"
+        )