agent-supra 1.0.0__tar.gz

agent_supra-1.0.0/.env.example

@@ -0,0 +1,33 @@
+# Copy to .env and fill in. Everything except DATABASE_URL and BASE_URL is optional.
+
+# Postgres in production. Hosting providers' postgres:// URLs work as-is.
+DATABASE_URL=sqlite:///supervisor.db
+# The public URL people and agents use. https:// turns on secure cookies and HSTS.
+BASE_URL=http://localhost:8000
+APP_NAME=Agent Supra
+CONTACT_EMAIL=sanchitp498@gmail.com
+
+# Set to false after launch if you want invite-only (create users with `agent-supra create-user`).
+ALLOW_SIGNUP=true
+# Delete runs older than this many days (0 = keep forever).
+RETENTION_DAYS=30
+
+# Required for the Vercel retention cron. Use a random value of at least 16 characters.
+CRON_SECRET=
+
+# Rate limits (per server process).
+RATE_LIMIT_EVENTS_PER_MIN=1200
+RATE_LIMIT_AUTH_PER_MIN=10
+
+# Server processes. 2 is fine for a small launch.
+WEB_CONCURRENCY=2
+
+# Email alerts (any SMTP provider: Resend, Postmark, SES, Gmail app password...).
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_FROM=
+
+# Extra model prices, USD per million tokens: {"model-name": [input, output]}
+AGENT_SUPRA_PRICES=

agent_supra-1.0.0/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PORT=8000
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY agent_supra ./agent_supra
+RUN pip install ".[server]" && useradd --create-home --uid 10001 app
+USER app
+
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request,os; urllib.request.urlopen(f'http://127.0.0.1:{os.environ.get(\"PORT\",\"8000\")}/healthz', timeout=4)"
+
+# Runs migrations, then the server. Configure with environment variables (see .env.example).
+CMD ["agent-supra", "serve"]

agent_supra-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanchit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_supra-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include .env.example Dockerfile docker-compose.yml render.yaml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include scripts *.py

agent_supra-1.0.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: agent-supra
+Version: 1.0.0
+Summary: Notice when an unattended AI agent is stuck, pause it, and show why.
+Author: Sanchit
+License-Expression: MIT
+Project-URL: Homepage, https://agentsupra.in
+Project-URL: Documentation, https://agentsupra.in/docs/quickstart
+Project-URL: Repository, https://github.com/voidpusher/agent-supra
+Project-URL: Issues, https://github.com/voidpusher/agent-supra/issues
+Keywords: ai agents,llm,gemini,monitoring,cost control,observability
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.29; extra == "server"
+Requires-Dist: sqlalchemy>=2.0; extra == "server"
+Requires-Dist: psycopg[binary]>=3.1; extra == "server"
+Requires-Dist: jinja2>=3.1; extra == "server"
+Requires-Dist: python-multipart>=0.0.9; extra == "server"
+Provides-Extra: dev
+Requires-Dist: agent-supra[server]; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: google-genai>=1.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+Requires-Dist: cryptography>=42; extra == "dev"
+Dynamic: license-file
+
+# Agent Supra
+
+Notice when an unattended AI agent is stuck, pause it before more money goes into a loop, and show exactly why.
+
+A spend cap can't tell a stuck agent from one working hard on a tough bug. Agent Supra watches **progress**: if an agent keeps changing code while its failing tests don't get any fewer, the run is flagged (or paused, once you opt in) with the evidence.
+
+- **SDK** (`pip install agent-supra`): no dependencies. Wraps Gemini, OpenAI and Anthropic clients.
+- **Hosted service**: dashboard, API keys, alerts to Slack and email, Postgres-backed. One Docker image.
+
+## Try it in two minutes (no accounts, no API keys)
+
+```bash
+pip install -e ".[dev]"
+agent-supra demo            # or: python -m agent_supra.demo
+```
+
+Two scripted agents fix a real bug in a tiny repo, running real pytest. One edits the code four times while the same tests fail and gets **paused**. The other fails twice, changes approach, passes, and is **left alone**. A timeline report is written to `supervisor_report.html`.
+
+## Run the service locally
+
+On Windows, see [the local PowerShell guide](docs/windows-local.md). The helper
+`python scripts/local.py serve` loads the repository's `.env` file; the bare
+`agent-supra serve` command reads exported environment variables.
+
+```bash
+cp .env.example .env
+agent-supra serve           # SQLite by default; http://localhost:8000
+```
+
+Or with Postgres, the way production runs:
+
+```bash
+docker compose up --build
+```
+
+Sign up, create an API key, then follow the quickstart at `/docs/quickstart`.
+
+## Connect an agent
+
+```python
+from google import genai
+from agent_supra import Client, SupervisedRun, SupervisorPaused
+
+sup = Client()   # AGENT_SUPRA_API_KEY and AGENT_SUPRA_URL from the environment
+task = sup.create_task("Fix failing checkout tests", budget_usd=3)
+
+with SupervisedRun(sup, task) as run:
+    gemini = run.wrap_gemini(genai.Client())
+    try:
+        while True:
+            run.check()                                   # raises SupervisorPaused when paused
+            reply = gemini.models.generate_content(model="gemini-3.5-flash-lite", contents=prompt)
+            run.tool("edit_file", apply_fix, reply.text, rev=git_rev())
+            result = run.tool("run_tests", run_tests, rev=git_rev())
+            run.report_tests(result.all_ids, result.failing_ids, rev=git_rev())
+            if not result.failing_ids:
+                run.finish("success")
+                break
+    except SupervisorPaused as paused:
+        print("Paused:", paused.reason)                   # don't retry; review it in the dashboard
+```
+
+| Call | What it does |
+| --- | --- |
+| `Client(fail_mode="open")` | Hosted backend. If the service is down, `"open"` keeps the agent running and buffers events; `"closed"` treats it as paused |
+| `run.wrap_gemini(client)` | `google.genai.Client()`: `models.generate_content`, `generate_content_stream`, `chats`, `aio`. Also the older `GenerativeModel` |
+| `run.wrap_openai(client)` | `chat.completions.create` and `responses.create`. Streaming needs `stream_options={"include_usage": True}` |
+| `run.wrap_anthropic(client)` | `messages.create`, including streams |
+| `run.record_model_call(model, in, out)` | Any other model |
+| `run.check()` | Refuses the next step if the run is paused or stopped |
+| `run.tool(name, fn, ..., rev=)` | Runs a tool and records success or failure (fingerprints only, not the raw arguments or errors) |
+| `run.report_tests(suite, failing, rev=)` | The main progress signal |
+| `run.child()` | A sub-agent run sharing the task's budget |
+| `run.finish("success" / "failed" / "unknown")` | Final outcome |
+
+Wrapped clients check with the supervisor **before** each model call, so a paused run never reaches the provider.
+
+A complete, runnable Gemini agent is in [`examples/gemini_agent.py`](examples/gemini_agent.py). See [docs/testing-with-gemini.md](docs/testing-with-gemini.md).
+
+## Detection rules
+
+| Rule | Fires when | Default |
+| --- | --- | --- |
+| No progress | 4 attempts in a row without the number of failing tests reaching a new low, while the code changes. Swapping one failure for another doesn't count as progress | Pause, once observation mode is off |
+| Exact repeat | The same failure with no code change, or a tool failing with the same arguments and error | Pause, once observation mode is off |
+| Going in circles | Flipping between two versions of the code with the same failures | Flag |
+| Context running away | Input tokens rising call after call (2x over 5 calls) with no progress, or over a ceiling you set | Flag |
+| Budget | Estimated task spend reaches the budget, across all runs and sub-agents | Always enforced |
+| Call cap | The next model call would exceed the task's cap | Always enforced |
+
+Safeguards: deleting a failing test isn't progress; network and rate-limit errors never count; if events go missing, the run is only flagged, never paused. New workspaces start in **observation mode** (flag only) so people can check the rules on their own agents before anything gets paused.
+
+## Configuration
+
+All server settings are environment variables. See [`.env.example`](.env.example).
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DATABASE_URL` | `sqlite:///supervisor.db` | Postgres in production (`postgres://` URLs work) |
+| `BASE_URL` | `http://localhost:8000` | Public URL; `https://` turns on secure cookies and HSTS |
+| `APP_NAME` | `Agent Supra` | Product name shown everywhere |
+| `ALLOW_SIGNUP` | `true` | `false` for invite-only (`agent-supra create-user`) |
+| `RETENTION_DAYS` | `30` | Run and server-error data older than this is deleted every 6 hours or by the daily cron |
+| `SMTP_*` | unset | Email alerts |
+| `AGENT_SUPRA_PRICES` | unset | Extra model prices, `{"model": [input, output]}` USD per 1M tokens |
+
+## Deploying
+
+See [docs/deploying.md](docs/deploying.md). Short version: push to GitHub, create a Render Blueprint from `render.yaml`, set `BASE_URL`.
+
+## Security
+
+- Passwords: scrypt. API keys and sessions: stored only as SHA-256 hashes; keys are shown once.
+- Every API request is scoped to the key's workspace; another workspace's runs return 404.
+- Dashboard forms are CSRF-protected; cookies are HttpOnly and SameSite.
+- Rate limits on events and on login/sign-up; request size limits; strict security headers.
+- Slack webhooks must point at `hooks.slack.com`, so the setting can't be used to reach internal URLs.
+- Prompts, model replies and code are never sent; tool arguments and errors are sent only as keyed fingerprints. Set `AGENT_SUPRA_FP_KEY` in your agents to make them unguessable.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest                                  # 84 tests on SQLite
+TEST_DATABASE_URL=postgresql+psycopg://user:pass@localhost/test python -m pytest   # on Postgres
+```
+
+CI (`.github/workflows/tests.yml`) runs both.
+
+## Limits worth knowing
+
+- **Costs are estimates** from token counts and the price table (Gemini prices built in, checked 13 Oct 2026). Not your invoice.
+- **Pausing is cooperative**: in-flight calls and tools finish. Agents that call the provider directly, bypassing the wrapper, are not stopped.
+- **Budgets are checked, not reserved**: several sub-agents running in parallel can each make one more call after the budget is crossed.
+- Rate limits are per server process.
+- Thresholds are starting points. Tune them in observation mode on real runs.
+
+MIT licensed.

agent_supra-1.0.0/README.md

@@ -0,0 +1,138 @@
+# Agent Supra
+
+Notice when an unattended AI agent is stuck, pause it before more money goes into a loop, and show exactly why.
+
+A spend cap can't tell a stuck agent from one working hard on a tough bug. Agent Supra watches **progress**: if an agent keeps changing code while its failing tests don't get any fewer, the run is flagged (or paused, once you opt in) with the evidence.
+
+- **SDK** (`pip install agent-supra`): no dependencies. Wraps Gemini, OpenAI and Anthropic clients.
+- **Hosted service**: dashboard, API keys, alerts to Slack and email, Postgres-backed. One Docker image.
+
+## Try it in two minutes (no accounts, no API keys)
+
+```bash
+pip install -e ".[dev]"
+agent-supra demo            # or: python -m agent_supra.demo
+```
+
+Two scripted agents fix a real bug in a tiny repo, running real pytest. One edits the code four times while the same tests fail and gets **paused**. The other fails twice, changes approach, passes, and is **left alone**. A timeline report is written to `supervisor_report.html`.
+
+## Run the service locally
+
+On Windows, see [the local PowerShell guide](docs/windows-local.md). The helper
+`python scripts/local.py serve` loads the repository's `.env` file; the bare
+`agent-supra serve` command reads exported environment variables.
+
+```bash
+cp .env.example .env
+agent-supra serve           # SQLite by default; http://localhost:8000
+```
+
+Or with Postgres, the way production runs:
+
+```bash
+docker compose up --build
+```
+
+Sign up, create an API key, then follow the quickstart at `/docs/quickstart`.
+
+## Connect an agent
+
+```python
+from google import genai
+from agent_supra import Client, SupervisedRun, SupervisorPaused
+
+sup = Client()   # AGENT_SUPRA_API_KEY and AGENT_SUPRA_URL from the environment
+task = sup.create_task("Fix failing checkout tests", budget_usd=3)
+
+with SupervisedRun(sup, task) as run:
+    gemini = run.wrap_gemini(genai.Client())
+    try:
+        while True:
+            run.check()                                   # raises SupervisorPaused when paused
+            reply = gemini.models.generate_content(model="gemini-3.5-flash-lite", contents=prompt)
+            run.tool("edit_file", apply_fix, reply.text, rev=git_rev())
+            result = run.tool("run_tests", run_tests, rev=git_rev())
+            run.report_tests(result.all_ids, result.failing_ids, rev=git_rev())
+            if not result.failing_ids:
+                run.finish("success")
+                break
+    except SupervisorPaused as paused:
+        print("Paused:", paused.reason)                   # don't retry; review it in the dashboard
+```
+
+| Call | What it does |
+| --- | --- |
+| `Client(fail_mode="open")` | Hosted backend. If the service is down, `"open"` keeps the agent running and buffers events; `"closed"` treats it as paused |
+| `run.wrap_gemini(client)` | `google.genai.Client()`: `models.generate_content`, `generate_content_stream`, `chats`, `aio`. Also the older `GenerativeModel` |
+| `run.wrap_openai(client)` | `chat.completions.create` and `responses.create`. Streaming needs `stream_options={"include_usage": True}` |
+| `run.wrap_anthropic(client)` | `messages.create`, including streams |
+| `run.record_model_call(model, in, out)` | Any other model |
+| `run.check()` | Refuses the next step if the run is paused or stopped |
+| `run.tool(name, fn, ..., rev=)` | Runs a tool and records success or failure (fingerprints only, not the raw arguments or errors) |
+| `run.report_tests(suite, failing, rev=)` | The main progress signal |
+| `run.child()` | A sub-agent run sharing the task's budget |
+| `run.finish("success" / "failed" / "unknown")` | Final outcome |
+
+Wrapped clients check with the supervisor **before** each model call, so a paused run never reaches the provider.
+
+A complete, runnable Gemini agent is in [`examples/gemini_agent.py`](examples/gemini_agent.py). See [docs/testing-with-gemini.md](docs/testing-with-gemini.md).
+
+## Detection rules
+
+| Rule | Fires when | Default |
+| --- | --- | --- |
+| No progress | 4 attempts in a row without the number of failing tests reaching a new low, while the code changes. Swapping one failure for another doesn't count as progress | Pause, once observation mode is off |
+| Exact repeat | The same failure with no code change, or a tool failing with the same arguments and error | Pause, once observation mode is off |
+| Going in circles | Flipping between two versions of the code with the same failures | Flag |
+| Context running away | Input tokens rising call after call (2x over 5 calls) with no progress, or over a ceiling you set | Flag |
+| Budget | Estimated task spend reaches the budget, across all runs and sub-agents | Always enforced |
+| Call cap | The next model call would exceed the task's cap | Always enforced |
+
+Safeguards: deleting a failing test isn't progress; network and rate-limit errors never count; if events go missing, the run is only flagged, never paused. New workspaces start in **observation mode** (flag only) so people can check the rules on their own agents before anything gets paused.
+
+## Configuration
+
+All server settings are environment variables. See [`.env.example`](.env.example).
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DATABASE_URL` | `sqlite:///supervisor.db` | Postgres in production (`postgres://` URLs work) |
+| `BASE_URL` | `http://localhost:8000` | Public URL; `https://` turns on secure cookies and HSTS |
+| `APP_NAME` | `Agent Supra` | Product name shown everywhere |
+| `ALLOW_SIGNUP` | `true` | `false` for invite-only (`agent-supra create-user`) |
+| `RETENTION_DAYS` | `30` | Run and server-error data older than this is deleted every 6 hours or by the daily cron |
+| `SMTP_*` | unset | Email alerts |
+| `AGENT_SUPRA_PRICES` | unset | Extra model prices, `{"model": [input, output]}` USD per 1M tokens |
+
+## Deploying
+
+See [docs/deploying.md](docs/deploying.md). Short version: push to GitHub, create a Render Blueprint from `render.yaml`, set `BASE_URL`.
+
+## Security
+
+- Passwords: scrypt. API keys and sessions: stored only as SHA-256 hashes; keys are shown once.
+- Every API request is scoped to the key's workspace; another workspace's runs return 404.
+- Dashboard forms are CSRF-protected; cookies are HttpOnly and SameSite.
+- Rate limits on events and on login/sign-up; request size limits; strict security headers.
+- Slack webhooks must point at `hooks.slack.com`, so the setting can't be used to reach internal URLs.
+- Prompts, model replies and code are never sent; tool arguments and errors are sent only as keyed fingerprints. Set `AGENT_SUPRA_FP_KEY` in your agents to make them unguessable.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest                                  # 84 tests on SQLite
+TEST_DATABASE_URL=postgresql+psycopg://user:pass@localhost/test python -m pytest   # on Postgres
+```
+
+CI (`.github/workflows/tests.yml`) runs both.
+
+## Limits worth knowing
+
+- **Costs are estimates** from token counts and the price table (Gemini prices built in, checked 13 Oct 2026). Not your invoice.
+- **Pausing is cooperative**: in-flight calls and tools finish. Agents that call the provider directly, bypassing the wrapper, are not stopped.
+- **Budgets are checked, not reserved**: several sub-agents running in parallel can each make one more call after the budget is crossed.
+- Rate limits are per server process.
+- Thresholds are starting points. Tune them in observation mode on real runs.
+
+MIT licensed.

agent_supra-1.0.0/agent_supra/__init__.py

@@ -0,0 +1,27 @@
+"""Agent Supra: notice when an unattended agent is stuck, pause it, show why.
+
+The SDK (this package's top level) has no dependencies. The server lives in
+``agent_supra.server`` and needs ``pip install 'agent-supra[server]'``.
+"""
+
+__version__ = "1.0.0"
+
+from .client import Client, SupervisorAPIError, SupervisorUnavailable  # noqa: E402
+from .detector import DEFAULT_POLICY, Finding, evaluate  # noqa: E402
+from .pricing import estimate_cost_micros, register_price  # noqa: E402
+from .sdk import SupervisedRun, SupervisorPaused, error_fingerprint, fingerprint  # noqa: E402
+
+__all__ = [
+    "Client", "SupervisedRun", "SupervisorPaused", "SupervisorAPIError", "SupervisorUnavailable",
+    "DEFAULT_POLICY", "Finding", "evaluate", "estimate_cost_micros", "register_price",
+    "error_fingerprint", "fingerprint", "Supervisor", "SupervisorError",
+]
+
+
+def __getattr__(name):
+    # Local, in-process supervisor (needs the server extra). Imported lazily so the
+    # SDK stays dependency-free.
+    if name in ("Supervisor", "SupervisorError"):
+        from . import server
+        return getattr(server, name)
+    raise AttributeError(name)

agent_supra-1.0.0/agent_supra/cli.py

@@ -0,0 +1,88 @@
+"""Command line: ``agent-supra serve | migrate | create-user | prune | demo``."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import sys
+
+
+def _settings():
+    from .server.settings import Settings
+    return Settings.from_env()
+
+
+def cmd_serve(args) -> int:
+    import uvicorn
+    from .server import db
+    db.migrate(db.make_engine(_settings().database_url))   # once, before workers start
+    uvicorn.run("agent_supra.server.app:create_app", factory=True, host=args.host, port=args.port,
+                workers=args.workers, proxy_headers=True, forwarded_allow_ips=os.environ.get("FORWARDED_ALLOW_IPS", "*"),
+                log_level="info")
+    return 0
+
+
+def cmd_migrate(_args) -> int:
+    from .server import db
+    version = db.migrate(db.make_engine(_settings().database_url))
+    print(f"Database is at schema version {version}.")
+    return 0
+
+
+def cmd_create_user(args) -> int:
+    from .server.accounts import Accounts
+    from .server.core import Supervisor, SupervisorError
+    sup = Supervisor(_settings().database_url)
+    password = os.environ.get("AGENT_SUPRA_NEW_PASSWORD") or getpass.getpass("Password (10+ characters): ")
+    try:
+        _, workspace = Accounts(sup.engine).signup(args.email, password, args.workspace)
+    except SupervisorError as exc:
+        print(f"Couldn't create the user: {exc}", file=sys.stderr)
+        return 1
+    print(f"Created {args.email} with workspace {workspace}.")
+    return 0
+
+
+def cmd_prune(args) -> int:
+    from .server.core import Supervisor
+    days = args.days if args.days is not None else _settings().retention_days
+    removed = Supervisor(_settings().database_url).prune(days)
+    print(f"Removed {removed} run(s) older than {days} days.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["demo"]:
+        # Hand everything after "demo" to the demo's own parser (--observe, --report, ...).
+        from .demo import main as demo_main
+        return demo_main(argv[1:])
+    parser = argparse.ArgumentParser(prog="agent-supra", description="Agent Supra server tools")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="run the web server (reads DATABASE_URL, BASE_URL, ...)")
+    serve.add_argument("--host", default=os.environ.get("HOST", "0.0.0.0"))
+    serve.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8000")))
+    serve.add_argument("--workers", type=int, default=int(os.environ.get("WEB_CONCURRENCY", "2")))
+    serve.set_defaults(fn=cmd_serve)
+
+    sub.add_parser("migrate", help="create or upgrade database tables").set_defaults(fn=cmd_migrate)
+
+    user = sub.add_parser("create-user", help="create an account (useful with ALLOW_SIGNUP=false)")
+    user.add_argument("email")
+    user.add_argument("--workspace", help="workspace name")
+    user.set_defaults(fn=cmd_create_user)
+
+    prune = sub.add_parser("prune", help="delete runs older than the retention window")
+    prune.add_argument("--days", type=int)
+    prune.set_defaults(fn=cmd_prune)
+
+    sub.add_parser("demo", help="run the two-agent demo locally (try: agent-supra demo --help)")
+
+    args = parser.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())