ags-cli 0.1.0__py3-none-any.whl

cli/commands/session.py

@@ -0,0 +1,219 @@
+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 _state_dir
+
+app = typer.Typer(help="Inspect, resume, branch, and clear sessions.")
+console = Console()
+
+
+@app.command("list")
+def list_sessions(limit: int = typer.Option(20, "--limit")) -> None:
+    client = HarnessClient()
+    rows = client.get("/sessions", limit=limit)
+    table = Table("id", "status", "objective")
+    for r in rows:
+        table.add_row(r["id"], r["status"], r["canonical_objective"][:60])
+    console.print(table)
+
+
+@app.command("show")
+def show(session_id: str = typer.Argument(...)) -> None:
+    client = HarnessClient()
+    data = client.get(f"/sessions/{session_id}")
+    console.print_json(data=data)
+    runs = client.get(f"/sessions/{session_id}/runs")
+    table = Table("run_id", "provider", "role", "status")
+    for r in runs:
+        table.add_row(r["id"], r["adapter_kind"], r["role"], r["status"])
+    console.print(table)
+
+
+@app.command("resume")
+def resume(
+    session_id: str = typer.Argument(...),
+    policy: str = typer.Option("single", "--policy", "-p"),
+    providers: str = typer.Option(None, "--providers"),
+    inline: bool = typer.Option(False, "--inline"),
+) -> None:
+    """Continue a session from its canonical summary."""
+    client = HarnessClient()
+    data = client.post(
+        f"/sessions/{session_id}/resume",
+        json={"policy": policy, "providers": providers.split(",") if providers else None},
+        inline=inline,
+    )
+    console.print(f"[green]resumed[/green] session {data['session_id']}")
+
+
+@app.command("branch")
+def branch(session_id: str = typer.Argument(...)) -> None:
+    """Branch a new session from canonical state."""
+    client = HarnessClient()
+    data = client.post(f"/sessions/{session_id}/branch", json={})
+    console.print(f"[green]branched[/green] -> {data['id']}")
+
+
+@app.command("workspace")
+def workspace(session_id: str = typer.Argument(...)) -> None:
+    """Show a session's private-workspace (worktree) state."""
+    client = HarnessClient()
+    st = client.get(f"/sessions/{session_id}/workspace") or {}
+    if st.get("workspace_mode") != "worktree":
+        console.print("[dim]session works directly in the main project folder[/dim]")
+        if st.get("fallback_reason"):
+            console.print(f"[yellow]({st['fallback_reason']})[/yellow]")
+        return
+    n = len(st.get("changed_files") or [])
+    console.print(f"[dim]branch[/dim]  {st.get('branch', '?')}  (base: {st.get('base', '?')})")
+    console.print(f"[dim]path[/dim]    {st.get('path', '?')}")
+    console.print(
+        f"[dim]state[/dim]   {n} changed file{'s' if n != 1 else ''}, "
+        f"{st.get('ahead', 0)} commit(s) ahead"
+        + (", dirty" if st.get("dirty") else "")
+    )
+    for f in st.get("changed_files") or []:
+        console.print(f"  · {f}")
+    if st.get("merged_at"):
+        console.print(f"[green]merged at {st['merged_at']}[/green]")
+
+
+@app.command("merge")
+def merge(
+    session_id: str = typer.Argument(...),
+    squash: bool = typer.Option(False, "--squash", help="Squash-merge to one commit."),
+    delete_worktree: bool = typer.Option(
+        False, "--delete-worktree", help="Remove the worktree + branch after merging."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Merge a session's private branch back into its base branch."""
+    client = HarnessClient()
+    if not yes:
+        st = client.get(f"/sessions/{session_id}/workspace") or {}
+        n = len(st.get("changed_files") or [])
+        console.print(
+            f"About to merge branch [bold]{st.get('branch', '?')}[/bold] "
+            f"({n} changed file(s)) into [bold]{st.get('base', '?')}[/bold]."
+        )
+        if not typer.confirm("Proceed?"):
+            raise typer.Exit(0)
+    out = client.post(
+        f"/sessions/{session_id}/merge",
+        json={"squash": squash, "delete_worktree": delete_worktree},
+    ) or {}
+    if out.get("merged"):
+        console.print(f"[green]✓ merged (commit {str(out.get('commit', ''))[:12]})[/green]")
+    elif out.get("nothing_to_merge"):
+        console.print("[cyan]nothing to merge — no new changes[/cyan]")
+    elif out.get("conflicts"):
+        console.print("[bold red]✗ merge conflicts (aborted):[/bold red]")
+        for f in out["conflicts"]:
+            console.print(f"  · {f}")
+    else:
+        console.print(f"[yellow]merge did not complete: {out.get('reason') or out}[/yellow]")
+
+
+@app.command("prune-worktrees")
+def prune_worktrees() -> None:
+    """Remove worktree directories for sessions that no longer exist."""
+    client = HarnessClient()
+    out = client.post("/sessions/prune-worktrees", json={}) or {}
+    console.print(f"[green]removed {out.get('removed', 0)} orphan worktree(s)[/green]")
+
+
+@app.command("compact")
+def compact(
+    older_than: int = typer.Option(..., "--older-than", min=1, help="Compact sessions older than N days."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without deleting."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Prune bulky token/tool_result events from old terminal sessions.
+
+    Keeps the essential audit trail (message, status, cost, adapter_meta,
+    tool_call, error, artifact). Shows a preview and asks for confirmation
+    before deleting. Use --dry-run to preview without committing."""
+    client = HarnessClient()
+    preview = client.post("/sessions/compact", json={"older_than_days": older_than, "dry_run": True})
+    sessions = preview["sessions"]
+    events = preview["events_deleted"]
+    if sessions == 0:
+        console.print("[green]Nothing to compact[/green] — no qualifying sessions found.")
+        return
+
+    console.print(
+        f"[bold]{sessions}[/bold] session(s) matched; "
+        f"[bold red]{events}[/bold red] event(s) will be deleted (token + tool_result)."
+    )
+    if dry_run:
+        console.print("[yellow]Dry run — no changes made.[/yellow]")
+        return
+
+    if not yes and not typer.confirm("Compact these sessions?"):
+        console.print("Aborted.")
+        return
+
+    result = client.post("/sessions/compact", json={"older_than_days": older_than, "dry_run": False})
+    console.print(
+        f"[green]Compacted {result['sessions']} session(s),[/green] "
+        f"deleted {result['events_deleted']} event(s)."
+    )
+
+
+@app.command("clear")
+def clear(
+    ids: list[str] = typer.Argument(None, help="Specific session ids to clear."),
+    all_: bool = typer.Option(False, "--all", help="Clear ALL sessions."),
+    status: str = typer.Option(None, "--status", help="Only this status (e.g. failed)."),
+    older_than: int = typer.Option(None, "--older-than", min=1, help="Only sessions older than N days."),
+    workspace: str = typer.Option(None, "--workspace", "-w", help="Scope to a workspace slug."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Permanently delete unwanted sessions (and their runs/events/memory) from the DB.
+
+    Combine filters (AND): --all, --status, --older-than, --workspace, or session ids.
+    Shows a preview and asks for confirmation before deleting."""
+    if not (all_ or status or older_than or workspace or ids):
+        console.print(
+            "[yellow]Nothing selected.[/yellow] Pick what to clear: --all, "
+            "--status <s>, --older-than <days>, --workspace <slug>, or session ids."
+        )
+        raise typer.Exit(1)
+
+    client = HarnessClient()
+    body = {
+        "all": all_, "status": status, "older_than_days": older_than,
+        "workspace": workspace, "ids": list(ids) if ids else None,
+    }
+    matches = client.post("/sessions/clear", json={**body, "dry_run": True})["sessions"]
+    if not matches:
+        console.print("[green]Nothing to clear[/green] — no sessions match.")
+        return
+
+    table = Table("id", "status", "objective")
+    for s in matches:
+        table.add_row(s["id"], s["status"], (s.get("canonical_objective") or "")[:60])
+    console.print(table)
+    console.print(f"[bold red]{len(matches)}[/bold red] session(s) will be permanently deleted.")
+    if not yes and not typer.confirm("Delete these sessions?"):
+        console.print("Aborted.")
+        return
+
+    result = client.post("/sessions/clear", json={**body, "dry_run": False})
+    deleted_ids = {s["id"] for s in result["sessions"]}
+    # Drop local active-session pointers that referenced a now-deleted session, so the
+    # next `ags chat` starts fresh instead of trying to resume a gone session.
+    cleared = 0
+    for f in _state_dir().glob("*.session"):
+        try:
+            if f.read_text().strip() in deleted_ids:
+                f.unlink()
+                cleared += 1
+        except OSError:
+            pass
+    note = f" (cleared {cleared} local pointer(s))" if cleared else ""
+    console.print(f"[green]Deleted {result['count']} session(s).[/green]{note}")

cli/commands/stats.py

@@ -0,0 +1,96 @@
+"""``ags stats`` — per-turn latency and token breakdown.
+
+Shows queue time, first-event latency, total time, and token usage for each
+run in a session. Defaults to the current workspace's session.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+from cli.commands.ask import _session_file
+
+console = Console()
+
+
+def stats(
+    session_id: str | None = typer.Argument(
+        None, help="Session ID to fetch stats for. Defaults to current workspace session."
+    ),
+    workspace: str = typer.Option("default", "--workspace", "-w", envvar="HARNESS_WORKSPACE"),
+    json_out: bool = typer.Option(False, "--json", help="Emit stats as JSON and exit."),
+) -> None:
+    """Show per-run latency and token breakdown for a session."""
+    # Resolve session_id: use argument, or fallback to workspace's current session
+    if session_id is None:
+        session_file = _session_file(workspace)
+        if not session_file.exists():
+            console.print(
+                f"[yellow]No session found for workspace '{workspace}'.\n"
+                f"Start one with: [bold]ags ask \"...\"[/bold][/yellow]"
+            )
+            raise typer.Exit(1)
+        session_id = session_file.read_text().strip()
+        if not session_id:
+            console.print(
+                f"[yellow]Session file is empty for workspace '{workspace}'.[/yellow]"
+            )
+            raise typer.Exit(1)
+
+    client = HarnessClient()
+    try:
+        stats_data = client.get(f"/sessions/{session_id}/stats")
+    except Exception as exc:
+        console.print(f"[red]Error fetching stats: {exc}[/red]")
+        raise typer.Exit(1)
+
+    if json_out:
+        console.print_json(data=stats_data)
+        return
+
+    # Build a Rich table
+    table = Table(title=f"Run latencies and tokens (session {session_id[:8]})", title_justify="left")
+    table.add_column("run id", style="dim")
+    table.add_column("provider")
+    table.add_column("queue (ms)", justify="right")
+    table.add_column("first event (ms)", justify="right")
+    table.add_column("total (ms)", justify="right")
+    table.add_column("prompt tokens", justify="right")
+    table.add_column("completion tokens", justify="right")
+    table.add_column("resume")
+
+    # Track totals
+    total_prompt = 0
+    total_completion = 0
+
+    for run in stats_data:
+        run_id = run["run_id"][:8]
+        provider = run["provider"]
+        queue_ms = str(run["queue_ms"]) if run["queue_ms"] is not None else "—"
+        first_event_ms = str(run["first_event_ms"]) if run["first_event_ms"] is not None else "—"
+        total_ms = str(run["total_ms"]) if run["total_ms"] is not None else "—"
+        prompt_tokens = run["tokens"]["prompt"]
+        completion_tokens = run["tokens"]["completion"]
+        resume = run["resume"] or "—"
+
+        table.add_row(
+            run_id, provider, queue_ms, first_event_ms, total_ms,
+            str(prompt_tokens), str(completion_tokens), resume,
+        )
+
+        total_prompt += int(run["tokens"]["prompt"] or 0)
+        total_completion += int(run["tokens"]["completion"] or 0)
+
+    # Add totals row
+    table.add_row(
+        "[bold]totals[/bold]", "", "", "", "",
+        f"[bold]{total_prompt}[/bold]", f"[bold]{total_completion}[/bold]", "",
+    )
+
+    console.print(table)

cli/commands/status.py

@@ -0,0 +1,36 @@
+"""``ags status`` — what am I pointed at right now?
+
+Answers the everyday questions: which project directory are the agents operating
+in, are they in read-only (plan) or write mode, which workspace, and which agent is
+the current default. Project dir and mode come from the running API (it is launched
+rooted in the project, with ``HARNESS_WRITE`` controlling the mode)."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from cli.client import APIError, HarnessClient
+from cli.commands.ask import _resolve_provider
+
+console = Console()
+
+
+def status(
+    workspace: str = typer.Option("default", "--workspace", "-w", envvar="HARNESS_WORKSPACE"),
+) -> None:
+    """Show the active project, mode (plan/write), workspace, and default agent."""
+    client = HarnessClient()
+    provider = _resolve_provider(None, workspace)
+    try:
+        st = client.get("/status", 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]agent[/bold]      {provider}  "
+        f"[dim](default; override per-turn with -P or `ags use`)[/dim]"
+    )
+    console.print(f"[bold]project[/bold]    {st.get('project_dir', '?')}")
+    console.print(f"[bold]mode[/bold]       {st.get('mode', '?')}")

cli/commands/task.py

@@ -0,0 +1,37 @@
+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="Create and inspect tasks.")
+console = Console()
+
+
+@app.command("create")
+def create(
+    objective: str = typer.Option(..., "--objective", "-o", help="What to accomplish."),
+    title: str = typer.Option("", "--title", "-t"),
+    workspace: str = typer.Option("default", "--workspace", "-w"),
+) -> None:
+    """Create a task."""
+    client = HarnessClient()
+    data = client.post(
+        "/tasks",
+        json={"objective": objective, "title": title or objective[:60], "workspace": workspace},
+    )
+    console.print(f"[green]Created task[/green] {data['id']}")
+    console.print_json(data=data)
+
+
+@app.command("list")
+def list_tasks(limit: int = typer.Option(20, "--limit")) -> None:
+    """List recent tasks."""
+    client = HarnessClient()
+    rows = client.get("/tasks", limit=limit)
+    table = Table("id", "title", "status")
+    for r in rows:
+        table.add_row(r["id"], r["title"], r["status"])
+    console.print(table)

cli/commands/usage.py

@@ -0,0 +1,86 @@
+"""``ags usage`` — all-providers usage table from the run ledger.
+
+Shows a table of runs, tokens, and cost for **every** provider recorded in
+the current workspace. For the per-provider view that also includes provider
+plan limits (e.g. 5-hour / weekly quota), use ``ags quota [provider]``.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cli.client import HarnessClient
+
+console = Console()
+
+
+def usage(
+    workspace: str = typer.Option(
+        "default", "--workspace", "-w", envvar="HARNESS_WORKSPACE",
+        help="Workspace to query.",
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Emit raw usage list as JSON and exit."),
+) -> None:
+    """Show all-providers usage totals from the run ledger.
+
+    Displays runs, tokens, and cost for every provider recorded in the
+    workspace. For the provider-scoped view that also includes plan limits,
+    use: [bold]ags quota[/bold]
+    """
+    client = HarnessClient()
+    rows = client.get("/usage", workspace=workspace)
+
+    if json_out:
+        console.print_json(data=rows)
+        return
+
+    if not rows:
+        console.print("[dim]No usage recorded yet.[/dim]")
+        return
+
+    table = Table(
+        title=f"AgentS usage — all providers (workspace: {workspace})",
+        title_justify="left",
+    )
+    for col in ("provider", "kind", "runs", "prompt tok", "completion tok", "total tok", "cost (USD)"):
+        table.add_column(col)
+
+    total_runs = 0
+    total_prompt = 0
+    total_completion = 0
+    total_tokens = 0
+    total_usd = 0.0
+
+    for row in rows:
+        table.add_row(
+            row["provider"],
+            row.get("kind", ""),
+            str(row["runs"]),
+            f"{row['prompt_tokens']:,}",
+            f"{row['completion_tokens']:,}",
+            f"{row['total_tokens']:,}",
+            f"${row['usd']:.4f}",
+        )
+        total_runs += int(row["runs"])
+        total_prompt += int(row["prompt_tokens"])
+        total_completion += int(row["completion_tokens"])
+        total_tokens += int(row["total_tokens"])
+        total_usd += float(row["usd"])
+
+    # Totals row
+    table.add_row(
+        "[bold]totals[/bold]", "",
+        f"[bold]{total_runs}[/bold]",
+        f"[bold]{total_prompt:,}[/bold]",
+        f"[bold]{total_completion:,}[/bold]",
+        f"[bold]{total_tokens:,}[/bold]",
+        f"[bold]${total_usd:.4f}[/bold]",
+    )
+
+    console.print(table)
+    console.print(
+        "[dim]AgentS's own accounting from the run ledger — "
+        "use [bold]ags quota[/bold] to see a single provider's plan limits.[/dim]\n"
+    )

cli/local.py

@@ -0,0 +1,84 @@
+"""Daemonless server management for the CLI.
+
+A single ``ags serve`` process backed by SQLite. The CLI auto-spawns it on first use and
+records its URL so every later command (and every terminal) finds it."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+LOCAL_PORT = 8770
+LOCAL_BASE_URL = f"http://localhost:{LOCAL_PORT}"
+API_URL_FILE = Path.home() / ".ags" / "api_url"
+PID_FILE = Path.home() / ".ags" / "server.pid"
+LOG_FILE = Path.home() / ".ags" / "server.log"
+
+
+def is_up(base_url: str) -> bool:
+    try:
+        r = httpx.get(f"{base_url}/api/v1/healthz", timeout=1.5)
+        return r.status_code == 200
+    except httpx.HTTPError:
+        return False
+
+
+def _write_api_url(base_url: str) -> None:
+    API_URL_FILE.parent.mkdir(parents=True, exist_ok=True)
+    API_URL_FILE.write_text(base_url)
+
+
+def _serve_command() -> list[str]:
+    """Command to launch the server using the INSTALLED package, never CWD code.
+
+    Prefer the ``ags`` console script (its ``sys.path`` is the bin dir, not the
+    current directory, so it can't be shadowed by a repo's own ``cli``/``harness``).
+    Fall back to ``python -P -m cli.main`` (``-P`` keeps CWD off ``sys.path``)."""
+    exe = shutil.which("ags") or (os.path.basename(sys.argv[0]) == "ags" and sys.argv[0])
+    if exe:
+        return [exe, "serve", "--port", str(LOCAL_PORT)]
+    return [sys.executable, "-P", "-m", "cli.main", "serve", "--port", str(LOCAL_PORT)]
+
+
+def spawn_server(base_url: str = LOCAL_BASE_URL, *, wait_s: float = 30.0) -> bool:
+    """Start a detached ``ags serve`` and wait until it answers health checks."""
+    PID_FILE.parent.mkdir(parents=True, exist_ok=True)
+    LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(LOG_FILE, "ab") as logf:
+        proc = subprocess.Popen(
+            _serve_command(),
+            stdout=logf, stderr=logf, stdin=subprocess.DEVNULL,
+            start_new_session=True,  # detach: survives this CLI process exiting
+        )
+    PID_FILE.write_text(str(proc.pid))
+    deadline = time.monotonic() + wait_s
+    while time.monotonic() < deadline:
+        if is_up(base_url):
+            _write_api_url(base_url)
+            return True
+        if proc.poll() is not None:  # server died on startup
+            return False
+        time.sleep(0.4)
+    return False
+
+
+def ensure_local_server() -> str | None:
+    """Return a reachable API base URL, auto-spawning the server if needed.
+
+    Returns None when nothing could be reached (the caller's connect-error message
+    then guides the user). Honors an explicit ``HARNESS_API_BASE_URL``."""
+    if env := os.environ.get("HARNESS_API_BASE_URL"):
+        return env
+    # Prefer a previously recorded URL if it's live.
+    if API_URL_FILE.exists() and (url := API_URL_FILE.read_text().strip()) and is_up(url):
+        return url
+    if is_up(LOCAL_BASE_URL):
+        _write_api_url(LOCAL_BASE_URL)
+        return LOCAL_BASE_URL
+    return LOCAL_BASE_URL if spawn_server() else None