agoralia-cli 0.1.0__tar.gz

agoralia_cli-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/

agoralia_cli-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: agoralia-cli
+Version: 0.1.0
+Summary: Agoralia CLI — the gated agent surface (MCP · REST · CLI) for compliant AI voice campaigns
+Project-URL: Homepage, https://agoralia.app
+Project-URL: Documentation, https://docs.agoralia.app
+Project-URL: Source, https://github.com/giacomocavalcabo/agoralia-v2
+Author: Agoralia
+License-Expression: MIT
+Keywords: agent,agoralia,ai,cli,mcp,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# agoralia-cli
+
+The **Agoralia CLI** — the third agent surface (alongside MCP and the REST API) for running
+compliant AI voice campaigns. It's a thin client over the *already-gated* REST API: same
+policy, same human-approval flow, same audit. It adds nothing privileged — the gate lives
+server-side; the CLI just speaks HTTP to it and renders the guided errors it returns.
+
+Every call is tagged `X-Agent-Surface: cli`, so the action audit records that it came from
+the CLI.
+
+## Install
+
+```bash
+pip install agoralia-cli
+```
+
+## Authenticate
+
+The CLI uses a Bearer token (the same kind the MCP surface uses).
+
+```bash
+export AGORALIA_TOKEN=...                          # your Agoralia access token
+export AGORALIA_API_URL=https://api.agoralia.app   # optional (defaults to localhost:8000)
+```
+
+## Usage
+
+```bash
+# Generative dashboard pages (the agent composes a view; you see it at /pages/<slug>)
+agoralia pages list
+agoralia pages get q2-reactivation-calls
+agoralia pages create ./spec.json
+
+# Human "go" queue — approve/deny dangerous agent actions
+agoralia approvals list
+agoralia approvals decide <approval-id> approved
+
+# Read-only audit of what your agents did
+agoralia activity --limit 50
+
+# Generic escape hatch to any gated route
+agoralia call GET /campaigns
+agoralia call POST /campaigns/<id>/start --data '{}'
+```
+
+## The approval flow
+
+Dangerous actions (launching a campaign, spending, deleting) are gated. When you hit one
+without an approval, the CLI tells you exactly what to do:
+
+```bash
+$ agoralia call POST /campaigns/abc/start
+⚠  Approval required before this action can run.
+   approval_id: appr_123
+   → A human must approve it (POST /approvals/{id}/decide), then retry with header X-Approval-Id.
+   Once approved, retry with: --approval-id appr_123
+
+# a human approves it…
+$ agoralia approvals decide appr_123 approved
+
+# …then retry
+$ agoralia call POST /campaigns/abc/start --approval-id appr_123
+```
+
+(Approval enforcement is controlled server-side by the `AGENT_APPROVAL_ENABLED` flag.)
+
+## Development
+
+```bash
+pip install -e .
+python -m pytest tests/
+python -m agoralia_cli --help   # same as the `agoralia` command
+```

agoralia_cli-0.1.0/README.md

@@ -0,0 +1,73 @@
+# agoralia-cli
+
+The **Agoralia CLI** — the third agent surface (alongside MCP and the REST API) for running
+compliant AI voice campaigns. It's a thin client over the *already-gated* REST API: same
+policy, same human-approval flow, same audit. It adds nothing privileged — the gate lives
+server-side; the CLI just speaks HTTP to it and renders the guided errors it returns.
+
+Every call is tagged `X-Agent-Surface: cli`, so the action audit records that it came from
+the CLI.
+
+## Install
+
+```bash
+pip install agoralia-cli
+```
+
+## Authenticate
+
+The CLI uses a Bearer token (the same kind the MCP surface uses).
+
+```bash
+export AGORALIA_TOKEN=...                          # your Agoralia access token
+export AGORALIA_API_URL=https://api.agoralia.app   # optional (defaults to localhost:8000)
+```
+
+## Usage
+
+```bash
+# Generative dashboard pages (the agent composes a view; you see it at /pages/<slug>)
+agoralia pages list
+agoralia pages get q2-reactivation-calls
+agoralia pages create ./spec.json
+
+# Human "go" queue — approve/deny dangerous agent actions
+agoralia approvals list
+agoralia approvals decide <approval-id> approved
+
+# Read-only audit of what your agents did
+agoralia activity --limit 50
+
+# Generic escape hatch to any gated route
+agoralia call GET /campaigns
+agoralia call POST /campaigns/<id>/start --data '{}'
+```
+
+## The approval flow
+
+Dangerous actions (launching a campaign, spending, deleting) are gated. When you hit one
+without an approval, the CLI tells you exactly what to do:
+
+```bash
+$ agoralia call POST /campaigns/abc/start
+⚠  Approval required before this action can run.
+   approval_id: appr_123
+   → A human must approve it (POST /approvals/{id}/decide), then retry with header X-Approval-Id.
+   Once approved, retry with: --approval-id appr_123
+
+# a human approves it…
+$ agoralia approvals decide appr_123 approved
+
+# …then retry
+$ agoralia call POST /campaigns/abc/start --approval-id appr_123
+```
+
+(Approval enforcement is controlled server-side by the `AGENT_APPROVAL_ENABLED` flag.)
+
+## Development
+
+```bash
+pip install -e .
+python -m pytest tests/
+python -m agoralia_cli --help   # same as the `agoralia` command
+```

agoralia_cli-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agoralia-cli"
+version = "0.1.0"
+description = "Agoralia CLI — the gated agent surface (MCP · REST · CLI) for compliant AI voice campaigns"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Agoralia" }]
+keywords = ["agoralia", "voice", "ai", "agent", "mcp", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Telephony",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://agoralia.app"
+Documentation = "https://docs.agoralia.app"
+Source = "https://github.com/giacomocavalcabo/agoralia-v2"
+
+[project.scripts]
+agoralia = "agoralia_cli.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agoralia_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/agoralia_cli", "README.md"]

agoralia_cli-0.1.0/src/agoralia_cli/__init__.py

@@ -0,0 +1,11 @@
+"""
+Agoralia CLI — the third agent surface (after MCP and REST).
+
+A thin client over the *already-gated* REST API: same policy core, same approval flow,
+same audit. It adds nothing privileged — it just speaks HTTP to the gate and tags every
+call `X-Agent-Surface: cli` so the audit knows the origin. The gating lives server-side;
+the CLI only renders the guided errors the gate returns. See docs/AGENT_LAYER.md.
+"""
+from agoralia_cli.client import ApprovalRequired, CliClient, CliError
+
+__all__ = ["CliClient", "CliError", "ApprovalRequired"]

agoralia_cli-0.1.0/src/agoralia_cli/__main__.py

@@ -0,0 +1,4 @@
+from agoralia_cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agoralia_cli-0.1.0/src/agoralia_cli/client.py

@@ -0,0 +1,55 @@
+"""HTTP client for the Agoralia CLI — a thin, gated client over the REST API."""
+import httpx
+
+
+class CliError(Exception):
+    """A non-approval error from the API (with the server's message/detail)."""
+
+
+class ApprovalRequired(CliError):
+    """The gate blocked a dangerous action pending human approval.
+
+    Carries the approval_id + remediation so the CLI can tell the user exactly what to
+    do (approve it, then retry with --approval-id). This is the guided-error contract
+    surfacing on the CLI, identical to MCP/REST.
+    """
+
+    def __init__(self, approval_id: str | None, remediation: list[str]):
+        self.approval_id = approval_id
+        self.remediation = remediation
+        super().__init__("Approval required before this action can run.")
+
+
+class CliClient:
+    """Speaks HTTP to the gated REST API. Auth = Bearer token; surface = cli."""
+
+    def __init__(self, base_url: str, token: str, *, approval_id: str | None = None, timeout: float = 30.0):
+        if not token:
+            raise CliError("Not authenticated. Set AGORALIA_TOKEN (or pass --token).")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.headers = {"Authorization": f"Bearer {token}", "X-Agent-Surface": "cli"}
+        if approval_id:
+            self.headers["X-Approval-Id"] = approval_id
+
+    def request(self, method: str, path: str, *, json: dict | None = None, params: dict | None = None) -> dict:
+        with httpx.Client(timeout=self.timeout) as client:
+            resp = client.request(method, f"{self.base_url}{path}", headers=self.headers, json=json, params=params)
+        return self._handle(resp)
+
+    def _handle(self, resp: httpx.Response) -> dict:
+        if resp.status_code == 204:
+            return {"ok": True}
+        try:
+            body = resp.json()
+        except Exception:
+            body = {}
+        if resp.is_success:
+            return body
+
+        detail = body.get("detail", body) if isinstance(body, dict) else body
+        # Guided error: a dangerous action awaiting human "go".
+        if isinstance(detail, dict) and detail.get("code") == "approval_required":
+            raise ApprovalRequired(detail.get("approval_id"), detail.get("remediation", []))
+        msg = detail.get("error") if isinstance(detail, dict) else detail
+        raise CliError(f"HTTP {resp.status_code}: {msg or 'request failed'}")

agoralia_cli-0.1.0/src/agoralia_cli/main.py

@@ -0,0 +1,205 @@
+"""
+Agoralia CLI entrypoint. Thin gated client over the REST API.
+
+  agoralia auth login --token <TOKEN>   # mint a token in the dashboard, then store it
+  # or: export AGORALIA_TOKEN=...        # Bearer token (same as the MCP surface)
+  # AGORALIA_API_URL defaults to https://api.agoralia.app
+
+  agoralia pages list
+  agoralia pages get <slug>
+  agoralia pages create spec.json
+  agoralia approvals list
+  agoralia approvals decide <id> approved
+  agoralia activity --limit 50
+  agoralia call GET /campaigns                 # generic escape hatch to any gated route
+  agoralia call POST /campaigns/<id>/start --approval-id <id>
+
+Every call is gated server-side and tagged surface=cli in the audit. Dangerous actions
+return a guided 'approval required' the CLI renders with the id + how to retry.
+"""
+import argparse
+import json
+import os
+import pathlib
+import sys
+
+from agoralia_cli.client import ApprovalRequired, CliClient, CliError
+
+DEFAULT_URL = "https://api.agoralia.app"
+CONFIG_FILE = pathlib.Path(os.path.expanduser("~/.agoralia/credentials.json"))
+
+
+def _load_config() -> dict:
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def _save_config(cfg: dict) -> None:
+    CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+    try:
+        CONFIG_FILE.chmod(0o600)  # token is a secret
+    except OSError:
+        pass
+
+
+def _resolve_token(args: argparse.Namespace) -> str:
+    return args.token or os.getenv("AGORALIA_TOKEN") or _load_config().get("token", "")
+
+
+def _resolve_url(args: argparse.Namespace) -> str:
+    return args.api_url or os.getenv("AGORALIA_API_URL") or _load_config().get("api_url") or DEFAULT_URL
+
+
+def _client(args: argparse.Namespace) -> CliClient:
+    return CliClient(_resolve_url(args), _resolve_token(args), approval_id=args.approval_id)
+
+
+def _handle_auth(args: argparse.Namespace) -> int:
+    if args.action == "login":
+        token = args.token or os.getenv("AGORALIA_TOKEN", "")
+        if not token:
+            print(
+                "No token provided. Mint one in the dashboard (Settings → CLI tokens, or "
+                "POST /cli/token), then run:\n  agoralia auth login --token <TOKEN>",
+                file=sys.stderr,
+            )
+            return 1
+        cfg = _load_config()
+        cfg["token"] = token
+        cfg["api_url"] = args.api_url or os.getenv("AGORALIA_API_URL") or DEFAULT_URL
+        _save_config(cfg)
+        print(f"Logged in. Token stored in {CONFIG_FILE} (api_url: {cfg['api_url']}).")
+        return 0
+    if args.action == "logout":
+        cfg = _load_config()
+        cfg.pop("token", None)
+        _save_config(cfg)
+        print("Logged out (token removed).")
+        return 0
+    if args.action == "status":
+        cfg = _load_config()
+        has = bool(_resolve_token(args))
+        print(json.dumps({
+            "authenticated": has,
+            "api_url": _resolve_url(args),
+            "token_source": "flag/env" if (args.token or os.getenv("AGORALIA_TOKEN")) else ("config" if cfg.get("token") else "none"),
+        }, indent=2))
+        return 0
+    return 1
+
+
+def _print(data) -> None:
+    print(json.dumps(data, indent=2, default=str))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agoralia", description="Agoralia CLI — gated agent surface")
+    p.add_argument("--api-url", help="API base URL (or AGORALIA_API_URL)")
+    p.add_argument("--token", help="Bearer token (or AGORALIA_TOKEN)")
+    p.add_argument("--approval-id", help="Retry a dangerous action with a granted approval id")
+    sub = p.add_subparsers(dest="resource", required=True)
+
+    auth = sub.add_parser("auth", help="Authenticate the CLI").add_subparsers(dest="action", required=True)
+    al = auth.add_parser("login", help="Store a CLI token")
+    al.add_argument("--token", help="CLI token (or AGORALIA_TOKEN)")
+    al.add_argument("--api-url", help="API base URL (default https://api.agoralia.app)")
+    auth.add_parser("logout", help="Remove the stored token")
+    auth.add_parser("status", help="Show auth status")
+
+    pages = sub.add_parser("pages", help="Generative dashboard pages").add_subparsers(dest="action", required=True)
+    pages.add_parser("list")
+    g = pages.add_parser("get"); g.add_argument("slug")
+    c = pages.add_parser("create"); c.add_argument("spec_file", help="path to a view-spec JSON file")
+
+    appr = sub.add_parser("approvals", help="Human-go queue").add_subparsers(dest="action", required=True)
+    appr.add_parser("list")
+    d = appr.add_parser("decide"); d.add_argument("id"); d.add_argument("decision", choices=["approved", "denied"])
+
+    act = sub.add_parser("activity", help="Audit of agent actions")
+    act.add_argument("--limit", type=int, default=50)
+
+    conns = sub.add_parser("connections", help="Remote MCP servers the copilot can use").add_subparsers(dest="action", required=True)
+    conns.add_parser("list")
+    cc = conns.add_parser("connect", help="Connect a remote MCP server")
+    cc.add_argument("name")
+    cc.add_argument("url")
+    cc.add_argument("--auth-token", help="OAuth bearer token (stored encrypted server-side)")
+    cc.add_argument("--allowed-tool", action="append", default=[], dest="allowed_tools",
+                    help="Whitelist a tool (repeatable). Omit to allow all tools.")
+    cd = conns.add_parser("disconnect"); cd.add_argument("id")
+
+    call = sub.add_parser("call", help="Generic gated request to any route")
+    call.add_argument("method", choices=["GET", "POST", "PATCH", "DELETE"])
+    call.add_argument("path")
+    call.add_argument("--data", help="JSON body (string or @file)")
+    return p
+
+
+def dispatch(args: argparse.Namespace, client: CliClient) -> dict:
+    if args.resource == "pages":
+        if args.action == "list":
+            return client.request("GET", "/pages")
+        if args.action == "get":
+            return client.request("GET", f"/pages/{args.slug}")
+        if args.action == "create":
+            with open(args.spec_file) as f:
+                spec = json.load(f)
+            return client.request("POST", "/pages", json={"spec": spec})
+
+    if args.resource == "approvals":
+        if args.action == "list":
+            return client.request("GET", "/approvals")
+        if args.action == "decide":
+            return client.request("POST", f"/approvals/{args.id}/decide", json={"decision": args.decision})
+
+    if args.resource == "activity":
+        return client.request("GET", "/actions", params={"limit": args.limit})
+
+    if args.resource == "connections":
+        if args.action == "list":
+            return client.request("GET", "/mcp-connections")
+        if args.action == "connect":
+            body = {"name": args.name, "url": args.url, "allowed_tools": args.allowed_tools}
+            if args.auth_token:
+                body["auth_token"] = args.auth_token
+            return client.request("POST", "/mcp-connections", json=body)
+        if args.action == "disconnect":
+            return client.request("DELETE", f"/mcp-connections/{args.id}")
+
+    if args.resource == "call":
+        body = None
+        if args.data:
+            raw = args.data[1:] and open(args.data[1:]).read() if args.data.startswith("@") else args.data
+            body = json.loads(raw)
+        return client.request(args.method, args.path, json=body)
+
+    raise CliError(f"Unknown command: {args.resource}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.resource == "auth":
+        return _handle_auth(args)
+    try:
+        result = dispatch(args, _client(args))
+        _print(result)
+        return 0
+    except ApprovalRequired as e:
+        print("⚠  Approval required before this action can run.", file=sys.stderr)
+        if e.approval_id:
+            print(f"   approval_id: {e.approval_id}", file=sys.stderr)
+        for step in e.remediation:
+            print(f"   → {step}", file=sys.stderr)
+        if e.approval_id:
+            print(f"   Once approved, retry with: --approval-id {e.approval_id}", file=sys.stderr)
+        return 2
+    except CliError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())