ags-cli 0.1.0__py3-none-any.whl

cli/commands/diff.py

@@ -0,0 +1,49 @@
+"""``ags diff [run_id]`` — show what an agent changed.
+
+Without a run ID: fetches the newest run (in the current workspace) that has a
+pre-run git snapshot and renders its diff.  With a run ID: fetches that specific
+run's diff.
+
+Output is rendered via Rich's :class:`~rich.syntax.Syntax` with the ``diff``
+lexer so added lines are green and removed lines are red in terminals that
+support color.
+"""
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.syntax import Syntax
+
+from cli.client import HarnessClient
+
+console = Console()
+
+
+def diff(
+    run_id: str = typer.Argument(
+        None,
+        help="Run ID to diff. Omit to use the newest run with a snapshot in this workspace.",
+    ),
+    workspace: str = typer.Option("default", "--workspace", "-w", envvar="HARNESS_WORKSPACE"),
+) -> None:
+    """Show the git diff produced by an agent run (requires a pre-run snapshot)."""
+    client = HarnessClient()
+
+    if run_id:
+        data = client.get(f"/runs/{run_id}/diff")
+    else:
+        data = client.get("/runs/diff/latest", workspace=workspace)
+
+    sha = data.get("snapshot", "")
+    diff_text: str = data.get("diff", "")
+    truncated: bool = data.get("truncated", False)
+
+    console.print(f"[dim]snapshot:[/dim] [cyan]{sha}[/cyan]")
+    if truncated:
+        console.print("[yellow]Warning: diff truncated at 1 MB[/yellow]")
+
+    if not diff_text.strip():
+        console.print("[dim]No changes detected.[/dim]")
+        return
+
+    console.print(Syntax(diff_text, "diff", theme="monokai", line_numbers=False))

cli/commands/doctor.py

@@ -0,0 +1,93 @@
+"""``ags doctor`` — end-to-end provider preflight check.
+
+Calls GET /doctor on the running API and renders a Rich table showing, for
+each enabled provider: binary, version, health, latency, model, MCP flag
+support, native-session eligibility, and any detected problems.
+
+Exit code 1 when any listed provider has problems.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import APIError, HarnessClient
+
+console = Console()
+
+
+def doctor(
+    provider: str | None = typer.Argument(
+        None, help="Filter to a single provider name. Omit to check all enabled providers."
+    ),
+) -> None:
+    """Run preflight health checks on all (or one) enabled provider(s)."""
+    client = HarnessClient()
+    try:
+        rows: list[dict] = client.get("/doctor")
+    except APIError as exc:
+        console.print(f"[red]✗ {exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    # Optional single-provider filter
+    if provider:
+        rows = [r for r in rows if r["provider"] == provider]
+        if not rows:
+            console.print(f"[yellow]No enabled provider named {provider!r}[/yellow]")
+            raise typer.Exit(1)
+
+    if not rows:
+        console.print("[dim]No enabled providers found.[/dim]")
+        return
+
+    table = Table(
+        title="Provider preflight",
+        title_justify="left",
+        show_lines=False,
+    )
+    table.add_column("provider", style="bold")
+    table.add_column("kind")
+    table.add_column("version")
+    table.add_column("health")
+    table.add_column("latency (ms)")
+    table.add_column("model")
+    table.add_column("MCP")
+    table.add_column("native")
+    table.add_column("problems")
+
+    has_problems = False
+    for r in rows:
+        problems = r.get("problems") or []
+        if problems:
+            has_problems = True
+
+        health_cell = "[green]ok[/green]" if r["health_ok"] else "[red]FAIL[/red]"
+        latency_cell = f"{r['latency_ms']:.0f}" if r.get("latency_ms") else "-"
+        mcp_val = r.get("mcp_ok")
+        mcp_cell = (
+            "-" if mcp_val is None
+            else ("[green]yes[/green]" if mcp_val else "[yellow]no[/yellow]")
+        )
+        native_cell = "[green]yes[/green]" if r.get("native_sessions") else "no"
+        problems_cell = (
+            "[red]" + "; ".join(problems) + "[/red]" if problems else "[dim]none[/dim]"
+        )
+
+        table.add_row(
+            r["provider"],
+            r.get("kind") or "-",
+            r.get("version") or "-",
+            health_cell,
+            latency_cell,
+            r.get("model") or "-",
+            mcp_cell,
+            native_cell,
+            problems_cell,
+        )
+
+    console.print(table)
+
+    if has_problems:
+        raise typer.Exit(1)

cli/commands/gui.py

@@ -0,0 +1,45 @@
+"""``ags gui`` — open the AgentS web dashboard.
+
+The web GUI is served by the local server at ``/ui`` (same origin as the API), so this
+just makes sure the server is up and opens the browser there."""
+
+from __future__ import annotations
+
+import webbrowser
+
+import httpx
+import typer
+from rich.console import Console
+
+from cli.local import ensure_local_server
+
+console = Console()
+
+
+def gui(
+    no_open: bool = typer.Option(
+        False, "--no-open", help="Print the URL but don't open a browser."
+    ),
+) -> None:
+    """Open the web GUI in your browser (starts the local server if needed)."""
+    base = ensure_local_server()
+    if not base:
+        console.print("[red]✗ couldn't reach or start the local server.[/red] Try `ags serve`.")
+        raise typer.Exit(1)
+
+    ui_url = f"{base}/ui/"
+    try:
+        built = httpx.get(ui_url, timeout=3.0).status_code == 200
+    except httpx.HTTPError:
+        built = False
+    if not built:
+        console.print(
+            "[yellow]The web GUI isn't built yet.[/yellow] Build it once with:\n"
+            "  [bold]cd webgui && npm install && npm run build[/bold]\n"
+            "then re-run [bold]ags gui[/bold]."
+        )
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] AgentS GUI: [bold]{ui_url}[/bold]")
+    if not no_open:
+        webbrowser.open(ui_url)

cli/commands/init.py

@@ -0,0 +1,20 @@
+"""``ags init`` — prepare the daemonless local instance (SQLite + seed)."""
+
+from __future__ import annotations
+
+import asyncio
+
+from rich.console import Console
+
+console = Console()
+
+
+def init() -> None:
+    """Create ~/.ags (config + SQLite schema + seeded providers). Idempotent."""
+    from harness.bootstrap import init_local
+    from harness.settings import HOME_DIR, get_settings
+
+    asyncio.run(init_local())
+    console.print(f"✓ AgentS initialized at [bold]{HOME_DIR}[/bold]")
+    console.print(f"  database: {get_settings().database_url}")
+    console.print("\nNext:  [bold]ags chat[/bold]   (the server auto-starts on first use)")

cli/commands/mcp.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+
+app = typer.Typer(help="List and test MCP servers (tools agents can call).")
+console = Console()
+
+
+@app.command("list")
+def list_servers() -> None:
+    """List configured MCP servers (from ``mcp.servers`` in config.yaml)."""
+    client = HarnessClient()
+    rows = client.get("/mcp/servers")
+    if not rows:
+        console.print(
+            "No MCP servers configured. Add them under [bold]mcp.servers[/bold] in "
+            "config.yaml, then re-run [bold]ags init[/bold]."
+        )
+        return
+    table = Table("name", "transport", "enabled", "read_only", "allowlist", "bind")
+    for r in rows:
+        allow = ", ".join(r.get("tool_allowlist") or []) or "all"
+        bind = r.get("bind") or {}
+        bind_s = (
+            f"ws={bind.get('workspaces') or 'all'} "
+            f"prov={bind.get('providers') or 'all'}"
+        )
+        table.add_row(
+            r["name"], r["transport"], str(r["enabled"]),
+            str(r["read_only"]), allow, bind_s,
+        )
+    console.print(table)
+
+
+@app.command("test")
+def test(name: str = typer.Argument(..., help="MCP server name.")) -> None:
+    """Connect to an MCP server and list the tools it advertises."""
+    client = HarnessClient()
+    data = client.post(f"/mcp/servers/{name}/test")
+    if data["ok"]:
+        tools = data.get("tools") or []
+        console.print(f"[green]{name}[/green] ok — {len(tools)} tool(s)")
+        for t in tools:
+            console.print(f"  • mcp__{name}__{t}")
+    else:
+        console.print(f"[red]{name}[/red] failed: {data.get('error')}")

cli/commands/memory.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+
+app = typer.Typer(help="Ingest and search shared memory.")
+console = Console()
+
+
+@app.command("ingest")
+def ingest(
+    content: str = typer.Argument(..., help="Fact/decision text to remember."),
+    workspace: str = typer.Option("default", "--workspace", "-w"),
+    mem_type: str = typer.Option("fact", "--type", help="fact|decision|preference|architecture"),
+    tags: str = typer.Option("", "--tags", help="Comma-separated tags."),
+) -> None:
+    """Ingest a memory item (secrets are redacted before storage)."""
+    client = HarnessClient()
+    data = client.post(
+        "/memory/ingest",
+        json={
+            "content": content, "workspace": workspace, "type": mem_type,
+            "tags": [t for t in tags.split(",") if t],
+        },
+    )
+    console.print(f"[green]stored[/green] {data['id']} redacted={data['redacted']}")
+
+
+@app.command("search")
+def search(
+    query: str = typer.Argument(...),
+    workspace: str = typer.Option("default", "--workspace", "-w"),
+    top_k: int = typer.Option(8, "--top-k", "-k"),
+) -> None:
+    """Search shared memory across providers."""
+    client = HarnessClient()
+    data = client.post(
+        "/memory/search", json={"query": query, "workspace": workspace, "top_k": top_k}
+    )
+    table = Table("score", "type", "content")
+    for hit in data["hits"]:
+        table.add_row(str(hit["score"]), hit["type"], hit["content"][:80])
+    console.print(table)
+
+
+@app.command("reindex")
+def reindex(
+    workspace: str | None = typer.Option(None, "--workspace", "-w",
+                                          help="Limit reindex to a specific workspace."),
+) -> None:
+    """Re-embed stale memory items after switching embedding provider or model.
+
+    Deletes embeddings produced by any model other than the currently active
+    embedder and re-embeds those items in batches of 64. Items already using
+    the active model are untouched.
+    """
+    client = HarnessClient()
+    payload: dict = {}
+    if workspace is not None:
+        payload["workspace"] = workspace
+    data = client.post("/memory/reindex", json=payload)
+    console.print(f"[green]reindexed[/green] {data['reindexed']} item(s)")

cli/commands/model.py

@@ -0,0 +1,73 @@
+"""``ags models list`` / ``ags model set`` — list and select a provider's model.
+
+    ags models list                 # models for every enabled provider
+    ags models list agy             # just agy's catalogue (marks the active one)
+    ags model set agy "Gemini 3.1 Pro (High)"   # select agy's model
+
+The convenience forms ``ags agy models list`` and ``ags agy model set <name>``
+are rewritten to these by the top-level dispatcher (see ``cli.main.route``).
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+from cli.commands.ask import _canon
+
+console = Console()
+
+models_app = typer.Typer(help="List provider models.", no_args_is_help=False)
+model_app = typer.Typer(help="Select a provider's model.", no_args_is_help=True)
+
+
+@models_app.command("list")
+def list_models(
+    provider: str | None = typer.Argument(
+        None, help="Provider to list (claude | agy | local | …). Omit for all."
+    ),
+) -> None:
+    """List available models for a provider (or all providers)."""
+    client = HarnessClient()
+    if provider:
+        names = [_canon(provider)]
+    else:
+        names = sorted({a["name"] for a in client.get("/adapters") if a.get("enabled", True)})
+
+    for name in names:
+        try:
+            data = client.get(f"/adapters/{name}/models")
+        except Exception as exc:  # noqa: BLE001 — surface per-provider, keep going
+            console.print(f"[yellow]{name}: {exc}[/yellow]")
+            continue
+        table = Table(title=f"{data['provider']} ({data['kind']})", title_justify="left")
+        table.add_column("", width=2)
+        table.add_column("model")
+        current = data.get("current")
+        for m in data["models"]:
+            mark = "[green]●[/green]" if m == current else " "
+            table.add_row(mark, f"[bold]{m}[/bold]" if m == current else m)
+        if not data["models"]:
+            table.add_row(" ", "[dim](provider exposes no model list)[/dim]")
+        console.print(table)
+        console.print(f"[dim]active: {current or '(none)'} — "
+                      f"set with `ags model set {data['provider']} \"<name>\"`[/dim]\n")
+
+
+@model_app.command("set")
+def set_model(
+    provider: str = typer.Argument(..., help="Provider to configure: claude | agy | local | …."),
+    name: str = typer.Argument(..., help="Model to select (quote names with spaces)."),
+) -> None:
+    """Select the active model for a provider (persists; used by future runs)."""
+    client = HarnessClient()
+    provider = _canon(provider)
+    try:
+        data = client.post(f"/adapters/{provider}/model", json={"model": name})
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"✓ [bold]{data['provider']}[/bold] now uses model "
+                  f"[bold]{data['current']}[/bold]")

cli/commands/policy.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+
+from cli.client import HarnessClient
+
+app = typer.Typer(help="Manage policies and approvals.")
+console = Console()
+
+
+@app.command("set")
+def set_policy(
+    name: str = typer.Argument(...),
+    kind: str = typer.Option(..., "--kind", help="routing|approval|egress|fs_allowlist"),
+    spec: str = typer.Option("{}", "--spec", help="JSON spec."),
+    workspace: str = typer.Option("default", "--workspace", "-w"),
+    priority: int = typer.Option(0, "--priority"),
+) -> None:
+    """Create or update a policy."""
+    client = HarnessClient()
+    data = client.put(
+        "/policies",
+        json={
+            "name": name, "kind": kind, "spec": json.loads(spec),
+            "workspace": workspace, "priority": priority,
+        },
+    )
+    console.print(f"[green]policy set[/green] {data['id']} ({data['kind']})")
+
+
+@app.command("approvals")
+def approvals(status: str = typer.Option(None, "--status")) -> None:
+    """List pending approvals."""
+    client = HarnessClient()
+    rows = client.get("/approvals", **({"status": status} if status else {}))
+    console.print_json(data=rows)
+
+
+@app.command("decide")
+def decide(
+    approval_id: str = typer.Argument(...),
+    status: str = typer.Option(..., "--status", help="approved|denied"),
+) -> None:
+    """Approve or deny a pending approval."""
+    client = HarnessClient()
+    data = client.post(
+        f"/approvals/{approval_id}/decide", json={"decision": status}
+    )
+    console.print(f"[green]decided[/green] {data['id']} -> {data['status']}")

cli/commands/project.py

@@ -0,0 +1,122 @@
+"""``ags project`` — show or change the project folder the agents work in, and
+the plan/write mode. Both are per-workspace runtime settings (stored server-side),
+so a change takes effect on the next message — no restart.
+
+    ags project                            # show active folder + mode
+    ags project set ~/code/myrepo          # point agents at a folder
+    ags project set /srv/repo --host box   # remote folder on ssh host "box"
+    ags project host box                   # move the project to an ssh host
+    ags project host --clear               # back to local
+    ags project mode read-only             # or: write
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from cli.client import APIError, HarnessClient
+
+console = Console()
+
+app = typer.Typer(help="Show or change the active project folder and mode.",
+                  no_args_is_help=False)
+
+_READONLY = {"read-only", "readonly", "ro", "r", "plan"}
+_WRITE = {"write", "rw", "w"}
+_WS = typer.Option("default", "--workspace", "-w", envvar="HARNESS_WORKSPACE")
+
+
+@app.callback(invoke_without_command=True)
+def _default(ctx: typer.Context, workspace: str = _WS) -> None:
+    """With no subcommand, show the active project folder and mode."""
+    if ctx.invoked_subcommand is not None:
+        return
+    client = HarnessClient()
+    try:
+        data = client.get("/project", workspace=workspace)
+    except APIError as exc:
+        console.print(f"[red]✗ {exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"[bold]workspace[/bold]  {workspace}")
+    console.print(f"[bold]project[/bold]    {data.get('project_dir', '?')}")
+    if data.get("project_host"):
+        console.print(f"[bold]host[/bold]       {data['project_host']} (remote via ssh)")
+    console.print(f"[bold]mode[/bold]       {data.get('mode', '?')}")
+
+
+@app.command("set")
+def set_project(
+    path: str = typer.Argument(..., help="Project folder the agents should operate in."),
+    host: str | None = typer.Option(
+        None, "--host", help="ssh alias/hostname the folder lives on (validated remotely)."),
+    workspace: str = _WS,
+) -> None:
+    """Point the agents at a project folder (validated to exist; persists).
+    With --host the folder is on that ssh host and is validated over ssh."""
+    body: dict = {}
+    if host is not None:
+        body["project_host"] = host
+        body["project_dir"] = path  # remote POSIX path — server validates over ssh
+    else:
+        p = Path(path).expanduser().resolve()
+        if not p.is_dir():
+            console.print(f"[red]✗ not a directory: {p}[/red]")
+            raise typer.Exit(1)
+        body["project_dir"] = str(p)
+    client = HarnessClient()
+    try:
+        data = client.put("/project", json=body, workspace=workspace)
+    except APIError as exc:
+        console.print(f"[red]✗ {exc}[/red]")
+        raise typer.Exit(1) from exc
+    where = f" on {data['project_host']}" if data.get("project_host") else ""
+    console.print(f"✓ [bold]{workspace}[/bold] project → {data.get('project_dir')}{where}")
+
+
+@app.command("host")
+def set_host(
+    host: str = typer.Argument("", help="ssh alias/hostname (empty with --clear)."),
+    clear: bool = typer.Option(False, "--clear", help="Back to a local project."),
+    workspace: str = _WS,
+) -> None:
+    """Move the project to a remote ssh host (or back to local with --clear)."""
+    if not clear and not host.strip():
+        console.print("[red]✗ give an ssh host, or --clear for local[/red]")
+        raise typer.Exit(1)
+    client = HarnessClient()
+    try:
+        data = client.put("/project", json={"project_host": "" if clear else host.strip()},
+                          workspace=workspace)
+    except APIError as exc:
+        console.print(f"[red]✗ {exc}[/red]")
+        raise typer.Exit(1) from exc
+    if data.get("project_host"):
+        console.print(f"✓ [bold]{workspace}[/bold] host → {data['project_host']}")
+    else:
+        console.print(f"✓ [bold]{workspace}[/bold] project is local")
+
+
+@app.command("mode")
+def mode(
+    value: str = typer.Argument(..., help="read-only (plan) | write (agents can edit)."),
+    workspace: str = _WS,
+) -> None:
+    """Switch between read-only (plan) and write mode (persists; next run picks it up)."""
+    v = value.strip().lower()
+    if v in _READONLY:
+        write = False
+    elif v in _WRITE:
+        write = True
+    else:
+        console.print("[red]✗ mode must be 'read-only' or 'write'[/red]")
+        raise typer.Exit(1)
+    client = HarnessClient()
+    try:
+        data = client.put("/project", json={"write_mode": write}, workspace=workspace)
+    except APIError as exc:
+        console.print(f"[red]✗ {exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"✓ [bold]{workspace}[/bold] mode → {data.get('mode')}")

cli/commands/quota.py

@@ -0,0 +1,107 @@
+"""``ags quota`` — usage + plan-limit status for the active (or named) provider.
+
+Two things are shown:
+
+1. **AgentS-tracked usage** — runs / tokens / cost AgentS has recorded for the
+   provider (from the run ledger). Always available, fully scriptable.
+2. **Provider plan quota** — the provider's own 5-hour / weekly limits. Neither the
+   `claude` nor `agy` CLI exposes these in a scriptable command (they live in the
+   interactive `/usage` and `/credits` views). Where a machine-readable path exists
+   (`antigravity-usage --json` for Antigravity) we use it; otherwise we point you to it.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+from cli.commands.ask import _canon, _resolve_provider
+
+console = Console()
+
+
+def quota(
+    provider: str | None = typer.Argument(
+        None, help="Provider to check: claude | agy | local | mock. Omit to use the active one."
+    ),
+    workspace: str = typer.Option("default", "--workspace", "-w", envvar="HARNESS_WORKSPACE"),
+    json_out: bool = typer.Option(False, "--json", help="Emit AgentS usage as JSON and exit."),
+) -> None:
+    """Show usage + plan-limit status for the active (or named) provider.
+
+    For the all-providers ledger totals (no plan limits), use: ags usage
+    """
+    prov = _canon(provider) if provider else _resolve_provider(None, workspace)
+    client = HarnessClient()
+
+    rows = client.get("/usage", workspace=workspace)
+    mine = next((r for r in rows if r["provider"] == prov), None)
+
+    if json_out:
+        console.print_json(data=mine or {"provider": prov, "runs": 0})
+        return
+
+    # 1) AgentS-tracked usage (always available).
+    table = Table(title=f"AgentS usage — {prov} (workspace: {workspace})", title_justify="left")
+    for col in ("runs", "prompt tok", "completion tok", "total tok", "cost (USD)"):
+        table.add_column(col)
+    if mine:
+        table.add_row(
+            str(mine["runs"]), f"{mine['prompt_tokens']:,}", f"{mine['completion_tokens']:,}",
+            f"{mine['total_tokens']:,}", f"${mine['usd']:.4f}",
+        )
+    else:
+        table.add_row("0", "0", "0", "0", "$0.0000")
+    console.print(table)
+    console.print(
+        "[dim]AgentS's own accounting from the run ledger — "
+        "not the provider's plan limit.[/dim]\n"
+    )
+
+    # 2) Provider plan quota (best available per provider).
+    if prov == "antigravity":
+        _antigravity_plan_quota()
+    elif prov == "claude":
+        console.print("[bold]Plan limits (claude):[/bold]")
+        console.print(
+            "  The `claude` CLI exposes 5-hour / weekly plan limits only via the "
+            "interactive [bold]/usage[/bold] command — there is no headless command.\n"
+            "  Check it with:  [bold]claude[/bold]  then type  [bold]/usage[/bold]   "
+            "(or open https://platform.claude.com/usage)."
+        )
+    elif prov in ("local", "mock"):
+        console.print(f"[dim]No plan quota for '{prov}' (self-hosted / mock).[/dim]")
+    else:
+        console.print(f"[dim]No known plan-quota source for '{prov}'.[/dim]")
+
+
+def _antigravity_plan_quota() -> None:
+    """Antigravity plan quota via the third-party `antigravity-usage` tool, if present."""
+    console.print("[bold]Plan limits (antigravity / AI Credits):[/bold]")
+    tool = shutil.which("antigravity-usage")
+    if not tool:
+        console.print(
+            "  No headless command in `agy` itself. Options:\n"
+            "  • interactive:  [bold]agy[/bold]  then type  [bold]/credits[/bold]\n"
+            "  • scriptable:   install [bold]antigravity-usage[/bold] "
+            "([dim]npm i -g antigravity-usage[/dim]) and re-run `ags quota agy`."
+        )
+        return
+    try:
+        out = subprocess.run(
+            [tool, "--json"], capture_output=True, text=True, timeout=30, check=False
+        )
+    except (subprocess.SubprocessError, OSError) as exc:  # noqa: BLE001
+        console.print(f"  [yellow]antigravity-usage failed: {exc}[/yellow]")
+        return
+    raw = (out.stdout or out.stderr).strip()
+    try:
+        console.print_json(data=json.loads(raw))
+    except json.JSONDecodeError:
+        console.print(raw or "  [yellow](no output; are you signed in to agy?)[/yellow]")