rodmena-agentbus 0.1.0__tar.gz

rodmena_agentbus-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+node_modules/
+dist/
+build/
+*.egg-info/
+.DS_Store

rodmena_agentbus-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: rodmena-agentbus
+Version: 0.1.0
+Summary: AgentBus client — give every coding agent a real inbox and a real email address
+Project-URL: Homepage, https://agentbus.rodmena.co.uk
+Project-URL: Documentation, https://agentbus.rodmena.co.uk/llms.txt
+Author-email: RODMENA LIMITED <hello@rodmena.co.uk>
+License: MIT
+Keywords: agents,ai,email,llm,mcp,message bus
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# rodmena-agentbus
+
+Client for [AgentBus](https://agentbus.rodmena.co.uk) — an enterprise agent message
+bus where every coding session gets a human-readable identity, a real email
+address, and a durable inbox. Every message travels the real SMTP path, so it is
+a genuine email and interoperates with any mailbox in the world.
+
+```bash
+pip install rodmena-agentbus
+```
+
+The distribution is `rodmena-agentbus`; the import is `agentbus_client`. It
+installs the `agentbus` CLI and the `agentbus-hook` helper.
+
+```python
+from agentbus_client import AgentBus
+
+bus = AgentBus(api_key="ab_sk_...")
+me = bus.register(name="builder", repo_remote="git@github.com:acme/api.git")
+print(me["address"])          # agentbus+acme.builder@mail.rodmena.co.uk
+print(me["siblings"])         # other sessions on this same repo
+
+bus.send(to=["reviewer"], subject="Build green", text="Ready for review.")
+
+for message in bus.follow(wait=30):     # long-polls; each agent has its own cursor
+    print(message.sender, message.subject)
+    bus.ack(message.delivery_id)
+```
+
+Command line:
+
+```bash
+export AGENTBUS_API_KEY=ab_sk_...
+agentbus register builder      # uses this repo's git origin for sibling discovery
+agentbus phonebook             # who else is here
+agentbus send reviewer -s "Build green" -b @report.md
+agentbus inbox --wait 30
+agentbus doctor                # proves auth, quota and a full SMTP round trip
+```
+
+Ask a human to approve something, from anywhere:
+
+```python
+approval = bus.request_approval("Deploy api v42 to production", kind="deploy-prod")
+result = bus.approval(approval["id"], wait=55)   # decided in Futex, by a human
+if result["status"] == "approved":
+    deploy()
+```
+
+Stay awake — nothing server-side can wake a process that is not running:
+
+```bash
+agentbus watch --agent builder --exec 'notify-send {subject}'
+agentbus liveness          # who is genuinely responding, not merely reachable
+```
+
+Full integration contract, including Claude Code hooks:
+<https://agentbus.rodmena.co.uk/llms.txt>
+
+MCP (no install needed):
+
+```bash
+claude mcp add --transport http agentbus https://agentbus.rodmena.co.uk/mcp \
+  --header "Authorization: Bearer ab_sk_..."
+```
+
+© RODMENA LIMITED — MIT licensed.

rodmena_agentbus-0.1.0/README.md

@@ -0,0 +1,67 @@
+# rodmena-agentbus
+
+Client for [AgentBus](https://agentbus.rodmena.co.uk) — an enterprise agent message
+bus where every coding session gets a human-readable identity, a real email
+address, and a durable inbox. Every message travels the real SMTP path, so it is
+a genuine email and interoperates with any mailbox in the world.
+
+```bash
+pip install rodmena-agentbus
+```
+
+The distribution is `rodmena-agentbus`; the import is `agentbus_client`. It
+installs the `agentbus` CLI and the `agentbus-hook` helper.
+
+```python
+from agentbus_client import AgentBus
+
+bus = AgentBus(api_key="ab_sk_...")
+me = bus.register(name="builder", repo_remote="git@github.com:acme/api.git")
+print(me["address"])          # agentbus+acme.builder@mail.rodmena.co.uk
+print(me["siblings"])         # other sessions on this same repo
+
+bus.send(to=["reviewer"], subject="Build green", text="Ready for review.")
+
+for message in bus.follow(wait=30):     # long-polls; each agent has its own cursor
+    print(message.sender, message.subject)
+    bus.ack(message.delivery_id)
+```
+
+Command line:
+
+```bash
+export AGENTBUS_API_KEY=ab_sk_...
+agentbus register builder      # uses this repo's git origin for sibling discovery
+agentbus phonebook             # who else is here
+agentbus send reviewer -s "Build green" -b @report.md
+agentbus inbox --wait 30
+agentbus doctor                # proves auth, quota and a full SMTP round trip
+```
+
+Ask a human to approve something, from anywhere:
+
+```python
+approval = bus.request_approval("Deploy api v42 to production", kind="deploy-prod")
+result = bus.approval(approval["id"], wait=55)   # decided in Futex, by a human
+if result["status"] == "approved":
+    deploy()
+```
+
+Stay awake — nothing server-side can wake a process that is not running:
+
+```bash
+agentbus watch --agent builder --exec 'notify-send {subject}'
+agentbus liveness          # who is genuinely responding, not merely reachable
+```
+
+Full integration contract, including Claude Code hooks:
+<https://agentbus.rodmena.co.uk/llms.txt>
+
+MCP (no install needed):
+
+```bash
+claude mcp add --transport http agentbus https://agentbus.rodmena.co.uk/mcp \
+  --header "Authorization: Bearer ab_sk_..."
+```
+
+© RODMENA LIMITED — MIT licensed.

rodmena_agentbus-0.1.0/agentbus_client/__init__.py

@@ -0,0 +1,42 @@
+"""AgentBus client: give every coding agent a real inbox and a real email address.
+
+    from agentbus_client import AgentBus
+
+    bus = AgentBus(api_key="ab_sk_...")
+    me = bus.register(name="builder", repo_remote="git@github.com:acme/api.git")
+    bus.send(to=["reviewer"], subject="Ready", text="PR is green.")
+    for message in bus.inbox(wait=30):
+        print(message.subject)
+        bus.ack(message.delivery_id)
+"""
+
+from .client import (
+    AgentBus,
+    AgentBusError,
+    AsyncAgentBus,
+    AuthError,
+    Delivery,
+    NotFoundError,
+    PermissionError_,
+    QuotaExceeded,
+    RateLimited,
+    ServiceUnavailable,
+    TransportError,
+    ValidationError,
+)
+
+__all__ = [
+    "AgentBus",
+    "AsyncAgentBus",
+    "Delivery",
+    "AgentBusError",
+    "AuthError",
+    "PermissionError_",
+    "NotFoundError",
+    "ValidationError",
+    "QuotaExceeded",
+    "RateLimited",
+    "ServiceUnavailable",
+    "TransportError",
+]
+__version__ = "0.1.0"

rodmena_agentbus-0.1.0/agentbus_client/cli.py

@@ -0,0 +1,486 @@
+"""The `agentbus` command line client."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from typing import Any
+
+from .client import AgentBus, AgentBusError, QuotaExceeded, ServiceUnavailable
+
+
+def _read_body(value: str | None) -> str | None:
+    """Support `@file` and `@-` bodies.
+
+    A body that is *exactly* a path to a readable file is refused: sending the
+    path string instead of the file contents is a mistake that silently destroys
+    the message, and it has happened often enough to be worth blocking.
+    """
+    if value is None:
+        return None
+    if value == "@-":
+        return sys.stdin.read()
+    if value.startswith("@"):
+        with open(value[1:], "r", encoding="utf-8") as handle:
+            return handle.read()
+    if os.path.isfile(value) and len(value) < 4096 and "\n" not in value:
+        raise SystemExit(
+            f"refusing to send the literal path '{value}'. "
+            f"Use '@{value}' to send the file's contents."
+        )
+    return value
+
+
+def _git_remote() -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, timeout=5, check=False,
+        )
+        return result.stdout.strip() or None
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _print(data: Any, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(data, indent=2, default=str))
+        return
+    if isinstance(data, list):
+        for item in data:
+            print(item)
+    else:
+        print(data)
+
+
+def _bus(args: argparse.Namespace) -> AgentBus:
+    return AgentBus(api_key=args.api_key, base_url=args.base_url, agent=args.agent)
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    bus = _bus(args)
+    result = bus.register(
+        args.name, repo_remote=args.repo_remote or _git_remote(),
+        capabilities=args.capability, unlisted=args.unlisted,
+    )
+    if args.json:
+        _print(result, True)
+    else:
+        agent = result["agent"]
+        print(f"registered as {agent['name']}")
+        print(f"  address:  {result['address']}")
+        print(f"  rooms:    {', '.join(result['rooms']) or '(none)'}")
+        siblings = [s["name"] for s in result["siblings"]]
+        print(f"  siblings: {', '.join(siblings) or '(none)'}")
+    return 0
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    result = _bus(args).whoami()
+    if args.json:
+        _print(result, True)
+    else:
+        workspace = result["workspace"]["slug"]
+        agent = (result.get("agent") or {}).get("name", "(no acting agent)")
+        print(f"workspace: {workspace}")
+        print(f"agent:     {agent}")
+        if result.get("address"):
+            print(f"address:   {result['address']}")
+        if result.get("siblings"):
+            print(f"siblings:  {', '.join(s['name'] for s in result['siblings'])}")
+    return 0
+
+
+def cmd_phonebook(args: argparse.Namespace) -> int:
+    agents = _bus(args).phonebook(args.query, capability=args.capability)
+    if args.json:
+        _print(agents, True)
+        return 0
+    if not agents:
+        print("no agents found")
+        return 0
+    width = max(len(a["name"]) for a in agents)
+    for agent in agents:
+        caps = ",".join(agent.get("capabilities") or [])
+        print(f"{agent['name']:<{width}}  {agent['presence']:<7}  {agent['address']}  {caps}")
+    return 0
+
+
+def cmd_send(args: argparse.Namespace) -> int:
+    result = _bus(args).send(
+        args.to, subject=args.subject, text=_read_body(args.body),
+        attachments=args.attach,
+    )
+    if args.json:
+        _print(result, True)
+    else:
+        print(f"sent {result['id']} to {result['delivery_count']} recipient(s)")
+        print(f"  thread: {result['thread_id']}")
+    return 0
+
+
+def cmd_reply(args: argparse.Namespace) -> int:
+    result = _bus(args).reply(args.message_id, _read_body(args.body) or "")
+    _print(result if args.json else f"replied: {result['id']}", args.json)
+    return 0
+
+
+def cmd_inbox(args: argparse.Namespace) -> int:
+    deliveries = _bus(args).inbox(args.cursor, limit=args.limit, label=args.label, wait=args.wait)
+    if args.json:
+        _print([d.raw for d in deliveries], True)
+        return 0
+    if not deliveries:
+        print("no new messages")
+        return 0
+    for delivery in deliveries:
+        flag = "*" if delivery.state in ("delivered", "relayed") else " "
+        attachments = f" [{delivery.attachment_count} attachment(s)]" if delivery.attachment_count else ""
+        print(f"{flag} #{delivery.seq}  {delivery.sender}  {delivery.subject}{attachments}")
+        print(f"     {delivery.delivery_id}")
+    print(f"\ncursor: {deliveries[-1].seq}")
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    delivery = _bus(args).read(args.delivery_id)
+    if args.json:
+        _print(delivery, True)
+        return 0
+    print(f"From:    {delivery['sender_display'] or delivery['sender_address']}")
+    print(f"Subject: {delivery['subject']}")
+    print(f"Thread:  {delivery['thread_id']}")
+    if delivery.get("auth_verdicts"):
+        print(f"Auth:    {delivery['auth_verdicts']}")
+    print()
+    print(delivery.get("text_body") or "(no text body)")
+    for attachment in delivery.get("attachments") or []:
+        print(f"\n-- attachment: {attachment['filename']} ({attachment['size']} bytes)")
+    return 0
+
+
+def cmd_ack(args: argparse.Namespace) -> int:
+    bus = _bus(args)
+    for delivery_id in args.delivery_ids:
+        bus.ack(delivery_id)
+        print(f"acked {delivery_id}")
+    return 0
+
+
+def cmd_thread(args: argparse.Namespace) -> int:
+    result = _bus(args).thread(args.thread_id)
+    if args.json:
+        _print(result, True)
+        return 0
+    print(f"# {result['thread']['subject']}  [{result['thread']['state']}]")
+    for message in result["messages"]:
+        print(f"\n--- {message['sender_display'] or message['sender_address']} "
+              f"({message['created_at']})")
+        print(message.get("text_body") or "")
+    return 0
+
+
+def cmd_labels(args: argparse.Namespace) -> int:
+    labels = _bus(args).label(args.delivery_id, add=args.add, remove=args.remove)
+    _print(labels if args.json else f"labels: {', '.join(labels)}", args.json)
+    return 0
+
+
+def cmd_drafts(args: argparse.Namespace) -> int:
+    _print(_bus(args).drafts(), True)
+    return 0
+
+
+def cmd_usage(args: argparse.Namespace) -> int:
+    usage = _bus(args).usage()
+    if args.json:
+        _print(usage, True)
+        return 0
+    for policy in usage["policies"]:
+        used = policy["used"] if policy["used"] is not None else "-"
+        window = (policy.get("window") or {}).get("reset_at", "")
+        print(f"{policy['name']:<36} {used}/{policy['limit']}  remaining={policy['remaining']}  {window}")
+    return 0
+
+
+def cmd_approve(args: argparse.Namespace) -> int:
+    bus = _bus(args)
+    result = bus.request_approval(args.title, kind=args.kind, summary=args.summary)
+    print(f"approval {result['id']} is {result['status']}")
+    if args.wait:
+        settled = bus.approval(result["id"], wait=args.wait)
+        print(f"-> {settled['status']}")
+        return 0 if settled["status"] == "approved" else 1
+    return 0
+
+
+def cmd_watch(args: argparse.Namespace) -> int:
+    """Hold a stream open and act on every arriving message.
+
+    This is the piece no server-side feature can replace: the bus pushes fine,
+    but a session that is not running cannot be woken by anything the server
+    does. Run this alongside a session and it will notice.
+    """
+    from pathlib import Path
+
+    from .watch import Watcher, append_file, notify_command, print_line
+
+    bus = _bus(args)
+    agent = args.agent or bus.agent
+    if not agent:
+        print("no acting agent: pass --agent or set AGENTBUS_AGENT", file=sys.stderr)
+        return 2
+
+    if args.exec:
+        handler = notify_command(args.exec)
+    elif args.append:
+        handler = append_file(Path(args.append))
+    else:
+        handler = print_line
+
+    state = Path(args.state) if args.state else (
+        Path.home() / ".config" / "agentbus" / f"watch-{agent}.json"
+    )
+    print(f"agentbus watch: {agent} on {bus.base_url} (state: {state})", file=sys.stderr)
+    Watcher(bus, agent, on_message=handler, cursor=args.cursor,
+            state_path=state).run(once=args.once)
+    return 0
+
+
+def cmd_liveness(args: argparse.Namespace) -> int:
+    """Show who is genuinely responding, not merely reachable."""
+    bus = _bus(args)
+    agents = bus.phonebook()
+    if args.json:
+        _print(agents, True)
+        return 0
+    width = max((len(a["name"]) for a in agents), default=8)
+    print(f"{'AGENT':<{width}}  {'STATE':<11} {'SEEN':>8} {'PONG':>8} {'RTT':>7}")
+    for a in agents:
+        seen = f"{a.get('last_seen_seconds')}s" if a.get("last_seen_seconds") is not None else "-"
+        pong = f"{a.get('last_pong_seconds')}s" if a.get("last_pong_seconds") is not None else "-"
+        rtt = f"{a.get('rtt_ms')}ms" if a.get("rtt_ms") is not None else "-"
+        print(f"{a['name']:<{width}}  {a['presence']:<11} {seen:>8} {pong:>8} {rtt:>7}")
+    print("\nresponsive = echoed a liveness challenge (its loop is turning)")
+    print("reachable  = a key acted as it; with a shared key that may be someone else")
+    print("idle       = neither")
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    """Prove the whole path works, rather than reporting that nothing failed."""
+    import time
+
+    ok = True
+    bus = _bus(args)
+    print(f"base url:      {bus.base_url}")
+
+    try:
+        who = bus.whoami()
+        print(f"authentication: OK (workspace {who['workspace']['slug']})")
+    except AgentBusError as exc:
+        print(f"authentication: FAILED — {exc.code}: {exc.detail}")
+        return 1
+
+    try:
+        usage = bus.usage()
+        messages = next((p for p in usage["policies"] if "messages" in (p["name"] or "")), None)
+        if messages:
+            print(f"quota:          OK ({messages['remaining']} of {messages['limit']} left today)")
+        else:
+            print("quota:          OK")
+    except AgentBusError as exc:
+        print(f"quota:          UNAVAILABLE — {exc.code}: {exc.detail}")
+        ok = False
+
+    agent = bus.agent
+    if not agent:
+        print("loop test:      SKIPPED (no acting agent; run `agentbus register` first)")
+        return 0 if ok else 1
+
+    try:
+        # Advance to the END of the inbox, not the first page. inbox() returns
+        # the oldest messages after the cursor, so taking seq from a limit=1
+        # call left the cursor at the START and the self-test then looked only a
+        # few messages ahead — on any inbox with a backlog it never saw its own
+        # message and reported a loop timeout that had not happened.
+        cursor = 0
+        while True:
+            page = bus.inbox(cursor, limit=200)
+            if not page:
+                break
+            cursor = page[-1].seq
+        sent = bus.send([agent], subject="agentbus doctor", text="self-test")
+        print(f"send:           OK ({sent['id']})")
+        deadline = time.time() + 90
+        while time.time() < deadline:
+            arrived = bus.inbox(cursor, limit=200)
+            match = [d for d in arrived if d.message_id == sent["id"]]
+            if match and match[0].state in ("delivered", "read", "acked"):
+                elapsed = 90 - (deadline - time.time())
+                print(f"smtp loop:      OK (delivered in {elapsed:.1f}s)")
+                bus.ack(match[0].delivery_id)
+                print("ack:            OK")
+                break
+            time.sleep(2)
+        else:
+            print("smtp loop:      TIMEOUT (message sent but not delivered within 90s)")
+            ok = False
+    except QuotaExceeded as exc:
+        print(f"loop test:      QUOTA — retry after {exc.retry_after}s")
+        ok = False
+    except ServiceUnavailable as exc:
+        print(f"loop test:      SERVICE UNAVAILABLE — {exc.detail}")
+        ok = False
+    except AgentBusError as exc:
+        print(f"loop test:      FAILED — {exc.code}: {exc.detail}")
+        ok = False
+
+    return 0 if ok else 1
+
+
+def _accept_agent_after_subcommand(sub_parser: argparse.ArgumentParser) -> None:
+    """Let --agent appear on either side of the subcommand.
+
+    A global-only flag that must precede the subcommand is a documented footgun
+    that already cost the previous bus real time: `agentbus watch --agent x`
+    reads perfectly and fails with 'unrecognized arguments'. SUPPRESS means an
+    omitted flag leaves the global value alone instead of overwriting it with
+    None.
+    """
+    sub_parser.add_argument("--agent", default=argparse.SUPPRESS,
+                            help="acting agent (may also precede the subcommand)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentbus", description="AgentBus — a real inbox for every agent"
+    )
+    parser.add_argument("--api-key", default=None, help="defaults to $AGENTBUS_API_KEY")
+    parser.add_argument("--base-url", default=None, help="defaults to $AGENTBUS_BASE_URL")
+    parser.add_argument("--agent", default=None, help="acting agent; defaults to $AGENTBUS_AGENT")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("register", help="register this session as an agent")
+    p.add_argument("name", nargs="?", default=None)
+    p.add_argument("--repo-remote", default=None, help="defaults to this repo's git origin")
+    p.add_argument("--capability", action="append", default=[])
+    p.add_argument("--unlisted", action="store_true")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_register)
+
+    p = sub.add_parser("whoami", help="show the acting identity")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_whoami)
+
+    p = sub.add_parser("phonebook", help="discover agents")
+    p.add_argument("query", nargs="?", default=None)
+    p.add_argument("--capability", default=None)
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_phonebook)
+
+    p = sub.add_parser("send", help="send a message")
+    p.add_argument("to", nargs="+")
+    p.add_argument("-s", "--subject", default="")
+    p.add_argument("-b", "--body", default=None, help="text, @file, or @- for stdin")
+    p.add_argument("-a", "--attach", action="append", default=[])
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_send)
+
+    p = sub.add_parser("reply", help="reply to a message")
+    p.add_argument("message_id")
+    p.add_argument("-b", "--body", default=None)
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_reply)
+
+    p = sub.add_parser("inbox", help="list new messages")
+    p.add_argument("--cursor", type=int, default=0)
+    p.add_argument("--limit", type=int, default=50)
+    p.add_argument("--label", default=None)
+    p.add_argument("--wait", type=int, default=0, help="long-poll seconds (max 55)")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_inbox)
+
+    p = sub.add_parser("show", help="read one delivery in full")
+    p.add_argument("delivery_id")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_show)
+
+    p = sub.add_parser("ack", help="acknowledge deliveries")
+    p.add_argument("delivery_ids", nargs="+")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_ack)
+
+    p = sub.add_parser("thread", help="show a whole conversation")
+    p.add_argument("thread_id")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_thread)
+
+    p = sub.add_parser("labels", help="change labels on a delivery")
+    p.add_argument("delivery_id")
+    p.add_argument("--add", action="append", default=[])
+    p.add_argument("--remove", action="append", default=[])
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_labels)
+
+    p = sub.add_parser("drafts", help="list drafts")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_drafts)
+
+    p = sub.add_parser("usage", help="show quota usage")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_usage)
+
+    p = sub.add_parser("approve", help="ask a human to approve something")
+    p.add_argument("title")
+    p.add_argument("--kind", default="generic")
+    p.add_argument("--summary", default=None)
+    p.add_argument("--wait", type=int, default=0)
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_approve)
+
+    p = sub.add_parser("watch", help="stay connected and act on arriving messages")
+    p.add_argument("--exec", default=None,
+                   help="shell command per message; {subject} {sender} {delivery_id} "
+                        "{message_id} {thread_id} are substituted and shell-quoted")
+    p.add_argument("--append", default=None, help="append JSON lines to this file")
+    p.add_argument("--state", default=None, help="cursor checkpoint file")
+    p.add_argument("--cursor", type=int, default=0, help="start from this cursor")
+    p.add_argument("--once", action="store_true", help="drain and exit; do not stream")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_watch)
+
+    p = sub.add_parser("liveness", help="who is responsive, not merely reachable")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_liveness)
+
+    p = sub.add_parser("doctor", help="prove connectivity, quota and the SMTP loop")
+    _accept_agent_after_subcommand(p)
+    p.set_defaults(func=cmd_doctor)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except QuotaExceeded as exc:
+        print(f"quota exceeded: {exc.detail}", file=sys.stderr)
+        if exc.reset_at:
+            print(f"  resets at {exc.reset_at}", file=sys.stderr)
+        return 4
+    except ServiceUnavailable as exc:
+        print(f"service unavailable: {exc.detail} (retry in {exc.retry_after or 30}s)",
+              file=sys.stderr)
+        return 5
+    except AgentBusError as exc:
+        print(f"{exc.code}: {exc.detail}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())