comodor 0.19.0__tar.gz → 0.19.2__tar.gz

{comodor-0.19.0 → comodor-0.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comodor
-Version: 0.19.0
+Version: 0.19.2
 Summary: Comodor — a self-improving terminal coding agent with a Rich TUI
 Project-URL: Homepage, https://comodor.ai
 Project-URL: Repository, https://github.com/ifekri/Comodor
@@ -174,7 +174,7 @@ Esc        stop it                F3         cycle mode
 | [What it can do](docs/tools.md) | The 13 tools, and when it uses each |
 | [Safety and permissions](docs/safety.md) | What it asks, and what it never does |
 | [From your phone](docs/telegram.md) | The Telegram bot, and who it answers |
-| [From WhatsApp](docs/whatsapp.md) | The Cloud API, the webhook, and Meta's limits |
+| [From WhatsApp](docs/whatsapp.md) | The Cloud API — longer to set up; Telegram does the same thing |
 | [Models on your machine](docs/local-models.md) | Downloading one, running it offline |
 | [Configuration](docs/configuration.md) | Every setting, and what wins |
 | [Cost](docs/cost.md) | Caching, budgets, paying less |

{comodor-0.19.0 → comodor-0.19.2}/README.md

@@ -147,7 +147,7 @@ Esc        stop it                F3         cycle mode
 | [What it can do](docs/tools.md) | The 13 tools, and when it uses each |
 | [Safety and permissions](docs/safety.md) | What it asks, and what it never does |
 | [From your phone](docs/telegram.md) | The Telegram bot, and who it answers |
-| [From WhatsApp](docs/whatsapp.md) | The Cloud API, the webhook, and Meta's limits |
+| [From WhatsApp](docs/whatsapp.md) | The Cloud API — longer to set up; Telegram does the same thing |
 | [Models on your machine](docs/local-models.md) | Downloading one, running it offline |
 | [Configuration](docs/configuration.md) | Every setting, and what wins |
 | [Cost](docs/cost.md) | Caching, budgets, paying less |

{comodor-0.19.0 → comodor-0.19.2}/docs/README.md

@@ -42,7 +42,7 @@ ends with the agent doing something useful.
 | | |
 |---|---|
 | [From your phone](telegram.md) | The Telegram bot: pairing, the buttons, and who it answers |
-| [From WhatsApp](whatsapp.md) | The Cloud API: the webhook, pairing, and Meta's limits |
+| [From WhatsApp](whatsapp.md) | The Cloud API — about twenty minutes and technical. Telegram does the same in one |
 | [Models on your machine](local-models.md) | Downloading one, running it offline, adding to the list |
 | [Questions](questions.md) | The form it puts up when a request reads two ways |
 | [How it learns](learning.md) | Corrections, lessons, rules, and the proof |

{comodor-0.19.0 → comodor-0.19.2}/src/comodor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.19.0'
-__version_tuple__ = version_tuple = (0, 19, 0)
+__version__ = version = '0.19.2'
+__version_tuple__ = version_tuple = (0, 19, 2)
 
 __commit_id__ = commit_id = None

{comodor-0.19.0 → comodor-0.19.2}/src/comodor/help.py

@@ -223,12 +223,21 @@ In Docker:  docker compose up   and open the address it prints.
 Full guide: docs/web.md"""),
 
     "whatsapp": ("From WhatsApp", """\
-  comodor whatsapp connect         the number, the token, the app secret
+  comodor whatsapp connect         guided: links each page, checks each value
   comodor whatsapp webhook         what to paste into Meta's dashboard
   comodor whatsapp pair            a one-time code that adds your number
   comodor whatsapp start -b        run it detached from this terminal
   comodor whatsapp status          what is set, who may talk, is it running
 
+Telegram does the same thing in about a minute. This takes about twenty and is
+technical, and most of it is in Meta's dashboard - so unless it has to be
+WhatsApp, `comodor help telegram` is the shorter road.
+
+What is NOT needed, because everybody assumes otherwise: no real phone number,
+no payment method, no business verification. The test number Meta creates
+messages five people for free, which is four more than one person talking to
+their own agent needs.
+
 Meta's Cloud API, which is the official one. The libraries that drive WhatsApp
 Web instead need Node, break whenever the web client changes, and are against
 the terms the account is held to - the failure mode there is somebody's phone
@@ -238,9 +247,13 @@ Two things work differently from Telegram, and both are Meta's design:
 
 *Messages are delivered, not fetched.* There is no long poll. Meta posts each
 message to a URL, so something of yours has to be reachable over HTTPS. The
-bot listens on localhost; a tunnel puts a real certificate in front of it:
+bot listens on localhost; `connect` starts a Cloudflare tunnel in front of it
+if cloudflared is installed, and `start --tunnel` brings one up alongside.
+
+A quick tunnel gets a new address every start, and Meta keeps delivering to
+the old one - so for a bot meant to keep running, make a named tunnel once:
 
-  cloudflared tunnel --url http://127.0.0.1:8770
+  cloudflared tunnel login && cloudflared tunnel create comodor
 
 *Every webhook is signed* with your app secret, and the signature is checked.
 Without one, anything that reaches that URL can hand the agent instructions

{comodor-0.19.0 → comodor-0.19.2}/src/comodor/setup.py

@@ -660,12 +660,21 @@ class SetupWizard:
             "otherwise.\n",
             style=self.theme.style("dim")))
 
+        # The two are not equal work and the list says so. WhatsApp needs a
+        # Meta app, an app secret and a public HTTPS address — twenty minutes
+        # of somebody else's dashboard — and it does exactly what the one-token
+        # option does. Somebody choosing it because it was listed second, and
+        # discovering that twenty minutes later, is a question that cost them
+        # their evening.
         wanted = self._choose(
             [("no", "Not now", "you can set either up later"),
              ("telegram", "Telegram",
-              "a bot from @BotFather — one token, set up here in a minute"),
+              "recommended — one token from @BotFather, about a minute, "
+              "nothing else to set up"),
              ("whatsapp", "WhatsApp",
-              "a Meta business number — needs an app at developers.facebook.com")],
+              "about twenty minutes and technical: a Meta app, an app secret "
+              "and a public HTTPS address. It does the same thing Telegram "
+              "does — pick this only if it has to be WhatsApp")],
             default=1, title="From your phone")
         if wanted == "whatsapp":
             self._point_at_whatsapp(step, total)
@@ -728,11 +737,13 @@ class SetupWizard:
                 "number, an access token, an\napp secret, and a public HTTPS "
                 "address for Meta to deliver to.\n\n"
                 "None of that can be made from a terminal, so it is its own "
-                "command:\n\n"
-                "   [bold]comodor whatsapp connect[/bold]"
-                "[dim]   walks through all four[/dim]\n"
-                "   [bold]comodor whatsapp webhook[/bold]"
-                "[dim]   what to paste into Meta[/dim]"),
+                "command — and\nthat one walks you through it, links each "
+                "page, checks each value as it\narrives, and starts the "
+                "tunnel for you:\n\n"
+                "   [bold]comodor whatsapp connect[/bold]\n\n"
+                "[dim]About twenty minutes the first time. No real number, no "
+                "card and no\nbusiness verification — the test number Meta "
+                "makes you messages five\npeople for free.[/dim]"),
             title=Text(" WhatsApp ", style=self.theme.style("title")),
             title_align="left", box=self.theme.box,
             border_style=self.theme.style("border"), padding=(1, 2)))

{comodor-0.19.0 → comodor-0.19.2}/src/comodor/whatsapp/commands.py

@@ -34,11 +34,15 @@ def register(subparsers: argparse._SubParsersAction) -> None:
                          help="from the app's Basic Settings")
     connect.add_argument("--url", dest="public_url",
                          help="the public HTTPS address of the webhook")
+    connect.add_argument("--tunnel", action="store_true",
+                         help="start a Cloudflare tunnel and use its address")
 
     start = actions.add_parser("start", help="run the bot")
     start.add_argument("--background", "-b", action="store_true",
                        help="detach from this terminal, so it keeps answering "
                             "after you close it")
+    start.add_argument("--tunnel", action="store_true",
+                       help="bring up a Cloudflare tunnel alongside it")
 
     actions.add_parser("stop", help="stop a bot running in the background")
 
@@ -86,7 +90,7 @@ def run(config: Config, args: argparse.Namespace) -> int:
     if action == "start":
         if getattr(args, "background", False):
             return _background(console, config)
-        return _start(console, config)
+        return _start(console, config, args)
     if action == "stop":
         return _stop(console, config)
     if action == "service":
@@ -96,6 +100,20 @@ def run(config: Config, args: argparse.Namespace) -> int:
     return 1
 
 
+def _ask(console, message: str) -> str:
+    """One line from the person at the terminal, or empty if there is nobody.
+
+    Empty rather than an exception on end-of-file: the wizard treats "nothing
+    entered" as "stop here and keep what we have", which is the right answer
+    for a pipe as well as for somebody pressing enter.
+    """
+    console.print(f"  [bold]{message}[/bold][dim]:[/dim] ", end="")
+    try:
+        return input()
+    except (EOFError, KeyboardInterrupt):
+        return ""
+
+
 def _save(config: Config) -> None:
     from .. import config as config_mod
 
@@ -113,6 +131,19 @@ def _connect(console, config: Config, args: argparse.Namespace) -> int:
     number_id = (args.number_id or "").strip()
     secret = (args.app_secret or "").strip()
 
+    if not (token or number_id or secret):
+        # Nothing given at all: walk it, rather than printing instructions and
+        # leaving somebody to run the command again with three flags they have
+        # to go and find first.
+        from ..ui import console as console_module
+        from .guide import walk
+
+        theme = console_module.prepare_theme(
+            config.ui.theme, config.ui.ascii_borders, no_color=False)
+        return walk(console, theme, config,
+                    ask=lambda message: _ask(console, message),
+                    save=_save)
+
     if not (token and number_id):
         console.print()
         console.print(Panel(
@@ -372,7 +403,7 @@ def _off(console, config: Config) -> int:
     return 0
 
 
-def _start(console, config: Config) -> int:
+def _start(console, config: Config, args: argparse.Namespace) -> int:
     from ..channels import WHATSAPP
     from .bot import Service
 
@@ -390,11 +421,35 @@ def _start(console, config: Config) -> int:
     console.print()
     console.print(f"  Working in [bold]{config.paths.project}[/bold]")
 
+    opened = None
+    if getattr(args, "tunnel", False):
+        from . import tunnel as tunnel_mod
+
+        opened, why = tunnel_mod.start_quick(config.whatsapp.port,
+                                             config.whatsapp.host)
+        if opened is None:
+            console.print(f"  [red]{why}[/red]\n")
+            return 1
+        where = opened.webhook(config.whatsapp.path)
+        console.print(f"  Tunnel [bold]{where}[/bold]")
+        if where != config.whatsapp.public_url:
+            # A quick tunnel gets a new hostname every run and Meta keeps
+            # delivering to the old one. Saying nothing here produces a bot
+            # that starts cleanly and never receives anything.
+            console.print("  [warn]This is not the address Meta has.[/warn] "
+                          "Update the Callback URL in")
+            console.print("  [dim]the dashboard, or make a named tunnel for "
+                          "an address that does not move.[/dim]")
+            config.whatsapp.public_url = where
+            _save(config)
+
     service = Service(config, announce=lambda line: console.print(f"  {line}"))
 
     def bye(*_: object) -> None:
         console.print("\n  Stopping.\n")
         service.stop()
+        if opened is not None:
+            opened.stop()
 
     try:
         signal.signal(signal.SIGINT, lambda *_: bye())

comodor-0.19.2/src/comodor/whatsapp/guide.py

@@ -0,0 +1,322 @@
+"""`comodor whatsapp connect`, walked through rather than documented.
+
+WhatsApp needs eight things done in a browser and a terminal, in order, and
+getting any one of them wrong produces a failure somewhere else entirely: a
+phone *number* pasted where the number *id* goes fails at the first send with
+"Unsupported post request"; a token from the dashboard works today and stops
+tomorrow; an app secret that never got saved makes every webhook unverified,
+which looks exactly like a bot nobody is talking to.
+
+So each value is taken one at a time and checked the moment it arrives — the
+token against Meta, the id for being an id, the secret for being a secret — and
+the two hard parts are done for you: the tunnel is started here, and Meta's
+verification callback is *waited for* rather than assumed, so the step ends
+when Meta has actually reached the endpoint and not when somebody has pressed
+enter.
+
+The wizard is the whole of `connect` when it is given no arguments. With them
+it is the one-line form, which is what a second machine or a script wants.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from rich.panel import Panel
+from rich.text import Text
+
+from ..config import Config
+from .api import Cloud, Unauthorised, WhatsAppError
+from .webhook import Endpoint, make_verify_token
+
+#: How long to wait for Meta to call the webhook back after somebody saves it.
+#: Meta calls within a second or two; a minute allows for reading the screen.
+VERIFY_PATIENCE = 180.0
+
+APPS = "https://developers.facebook.com/apps"
+
+
+@dataclass
+class Step:
+    """One thing to do, and where."""
+
+    title: str
+    body: str
+
+
+def _panel(console, theme, title: str, body: str) -> None:
+    console.print(Panel(Text.from_markup(body),
+                        title=Text(f" {title} ",
+                                   style=theme.style("title")),
+                        title_align="left", box=theme.box,
+                        border_style=theme.style("border"), padding=(1, 2)))
+
+
+def walk(console, theme, config: Config,
+         ask: Callable[[str], str],
+         save: Callable[[Config], None]) -> int:
+    """The whole of it, one step at a time. Returns an exit code."""
+    settings = config.whatsapp
+
+    # -- 1. the app ------------------------------------------------------- #
+    console.print()
+    _panel(console, theme, "1 of 5 — a Meta app",
+           f"Open [bold]{APPS}[/bold] and:\n\n"
+           "  • [bold]Create app[/bold] → type [bold]Business[/bold]\n"
+           "  • inside it, [bold]Add product[/bold] → [bold]WhatsApp[/bold] "
+           "→ Set up\n\n"
+           "Meta then makes you a [bold]test business number[/bold] and a test "
+           "account\nautomatically. No real number, no card, no business "
+           "verification —\nthe test number messages up to five people, which "
+           "is four more than\nyou need.\n\n"
+           "[dim]On that page you will see 'Phone number ID' and a temporary "
+           "token.[/dim]")
+    if ask("press enter when the WhatsApp product is added") is None:
+        return 130
+
+    # -- 2. the number id -------------------------------------------------- #
+    console.print()
+    _panel(console, theme, "2 of 5 — the phone number id",
+           "On [bold]WhatsApp → API Setup[/bold], copy [bold]Phone number ID"
+           "[/bold].\n\n"
+           "[dim]It is a long number under 'From'. Not the phone number "
+           "itself —\nthat is the single most common mistake here, and it "
+           "fails later\nwith an error that does not mention it.[/dim]")
+    number_id = ""
+    while True:
+        number_id = (ask("phone number id") or "").strip()
+        if not number_id:
+            console.print("  [dim]Nothing entered — stopping here. Run "
+                          "`comodor whatsapp connect` again when ready.[/dim]\n")
+            return 1
+        if number_id.isdigit() and len(number_id) >= 10:
+            break
+        bare = number_id.replace("+", "").replace(" ", "").replace("-", "")
+        if number_id.lstrip("+").replace(" ", "").replace("-", "").isdigit() \
+                and 7 <= len(bare) <= 15 and not number_id.isdigit():
+            # Written the way a phone number is written — spaces, dashes, a
+            # leading plus — which is the mistake worth naming, because it
+            # otherwise fails much later with an error about a "post request".
+            console.print("  [red]That looks like the phone number.[/red] "
+                          "The id is the long number beside it.")
+        elif not bare.isdigit():
+            console.print("  [red]An id is digits only.[/red]")
+        else:
+            console.print(f"  [red]Too short for an id[/red] [dim]({len(bare)} "
+                          f"digits; they are fifteen or so).[/dim]")
+
+    # -- 3. the token ------------------------------------------------------ #
+    console.print()
+    _panel(console, theme, "3 of 5 — an access token",
+           "The token on the API Setup page works, and [bold]expires in "
+           "twenty-four\nhours[/bold] — fine for trying this out, and it will "
+           "look like a bug tomorrow.\n\n"
+           "For one that does not expire:\n"
+           "  • [bold]business.facebook.com[/bold] → Business settings → "
+           "[bold]System users[/bold]\n"
+           "  • add one, [bold]Generate token[/bold], pick your app\n"
+           "  • tick [bold]whatsapp_business_messaging[/bold] and "
+           "[bold]whatsapp_business_management[/bold]\n\n"
+           "[dim]Either will do now; you can paste a permanent one later with"
+           "\n`comodor whatsapp connect --token …`.[/dim]")
+
+    token = ""
+    while True:
+        token = (ask("access token") or "").strip()
+        if not token:
+            console.print("  [dim]Stopping here.[/dim]\n")
+            return 1
+        console.print("  [dim]checking it with Meta…[/dim]")
+        try:
+            me = Cloud(token, number_id,
+                       version=settings.api_version).me()
+        except Unauthorised as problem:
+            console.print(f"  [red]Meta refused it.[/red] {problem}")
+            continue
+        except WhatsAppError as problem:
+            console.print(f"  [red]{problem}[/red]")
+            continue
+        shown = me.get("display_phone_number") or number_id
+        named = me.get("verified_name") or ""
+        console.print(f"  [green]Works.[/green] {shown}"
+                      + (f" ([dim]{named}[/dim])" if named else ""))
+        break
+
+    # -- 4. the app secret -------------------------------------------------- #
+    console.print()
+    _panel(console, theme, "4 of 5 — the app secret",
+           "In the same app: [bold]Settings → Basic[/bold], then [bold]Show"
+           "[/bold] beside App secret.\n\n"
+           "[dim]Every webhook Meta sends is signed with it, and Comodor "
+           "refuses any\ndelivery it cannot verify. Without one, anything that "
+           "reaches the\nendpoint could hand the agent instructions with your "
+           "number on them.[/dim]")
+    secret = ""
+    while True:
+        secret = (ask("app secret") or "").strip()
+        if not secret:
+            console.print("  [red]Without this nothing can be verified.[/red] "
+                          "[dim]Stopping here.[/dim]\n")
+            return 1
+        if len(secret) >= 24 and all(c in "0123456789abcdefABCDEF"
+                                     for c in secret):
+            break
+        console.print("  [red]That does not look like an app secret[/red] "
+                      "[dim](32 hex characters).[/dim]")
+
+    settings.token = token
+    settings.phone_number_id = number_id
+    settings.app_secret = secret
+    if not settings.verify_token:
+        settings.verify_token = make_verify_token()
+    settings.enabled = True
+    save(config)
+    console.print("  [dim]saved[/dim]")
+
+    # -- 5. somewhere for Meta to deliver to -------------------------------- #
+    return _webhook_step(console, theme, config, ask, save)
+
+
+def _webhook_step(console, theme, config: Config,
+                  ask: Callable[[str], str],
+                  save: Callable[[Config], None]) -> int:
+    """The hard one: a public HTTPS address, and Meta actually reaching it."""
+    from . import tunnel as tunnel_mod
+
+    settings = config.whatsapp
+    console.print()
+    _panel(console, theme, "5 of 5 — where Meta delivers",
+           "Meta posts each message to a URL, so something has to be "
+           "reachable from\nthe internet over HTTPS. Comodor listens on "
+           f"[bold]{settings.host}:{settings.port}[/bold];\nthe usual answer "
+           "is a Cloudflare tunnel, which needs no open port and\nno domain.")
+
+    started: Any = None
+    where = settings.public_url
+
+    binary = tunnel_mod.find_binary()
+    if binary is None:
+        console.print(f"  [dim]cloudflared is not installed — "
+                      f"{tunnel_mod.how_to_install()}[/dim]")
+        console.print("  [dim]Or use any address that already reaches this "
+                      "machine over HTTPS.[/dim]")
+        where = (ask(f"public https address for {settings.path}")
+                 or "").strip()
+        if not where:
+            return _unfinished(console, config, save)
+    else:
+        console.print(f"  [dim]cloudflared: {binary}[/dim]")
+        console.print("  [dim]starting a tunnel…[/dim]")
+        started, why = tunnel_mod.start_quick(settings.port, settings.host)
+        if started is None:
+            console.print(f"  [red]{why}[/red]")
+            where = (ask(f"public https address for {settings.path}")
+                     or "").strip()
+            if not where:
+                return _unfinished(console, config, save)
+        else:
+            where = started.webhook(settings.path)
+            console.print(f"  [green]tunnel up[/green]  {where}")
+            console.print(Text(
+                "  This address is temporary — a quick tunnel gets a new one "
+                "every time it\n  starts, so Meta would have to be told again "
+                "after a restart. For a bot\n  meant to keep running, make a "
+                "named tunnel once:",
+                style=theme.style("dim")))
+            console.print(Text(
+                "    cloudflared tunnel login && cloudflared tunnel create "
+                "comodor",
+                style=theme.style("accent")))
+
+    settings.public_url = where
+    save(config)
+
+    console.print()
+    _panel(console, theme, "Paste these into Meta",
+           "[bold]WhatsApp → Configuration[/bold], the [bold]Edit[/bold] "
+           "button beside Webhook:\n\n"
+           f"  [dim]Callback URL[/dim]\n  [bold]{where}[/bold]\n\n"
+           f"  [dim]Verify token[/dim]\n  [bold]{settings.verify_token}"
+           "[/bold]\n\n"
+           "Save it, then [bold]Manage[/bold] and tick [bold]messages[/bold].")
+
+    # The endpoint is stood up here so Meta's verification has something to
+    # reach: waiting for a callback that nothing is listening for would be a
+    # wizard that hangs, blaming the user for its own gap.
+    heard: list[str] = []
+    endpoint = Endpoint(verify_token=settings.verify_token,
+                        app_secret=settings.app_secret,
+                        path=settings.path, host=settings.host,
+                        port=settings.port,
+                        announce=lambda line: heard.append(line))
+    try:
+        endpoint.start()
+    except OSError as problem:
+        console.print(f"\n  [red]Could not listen on {settings.host}:"
+                      f"{settings.port}: {problem}[/red]")
+        console.print("  [dim]Something else may be using that port; change "
+                      "it with `whatsapp.port` in your config.[/dim]\n")
+        if started is not None:
+            started.stop()
+        return 1
+
+    console.print()
+    console.print(Text("  waiting for Meta to call it back…",
+                       style=theme.style("dim")))
+
+    ok = _wait_for_meta(heard)
+    endpoint.stop()
+    if started is not None:
+        started.stop()
+
+    console.print()
+    if not ok:
+        console.print(Text(
+            "  Meta has not called it yet.", style=theme.style("bad")))
+        console.print(Text(
+            "  Everything is saved. `comodor whatsapp webhook` shows the two "
+            "values\n  again, and `comodor whatsapp start` will answer the "
+            "check whenever it comes.",
+            style=theme.style("dim")))
+        console.print()
+        return 0
+
+    console.print(Text(f"  {theme.glyphs.check} Meta reached the webhook.",
+                       style=theme.style("good")))
+    console.print(Text(
+        "\n  One thing left — say who may talk to it:",
+        style=theme.style("dim")))
+    console.print(Text("    comodor whatsapp pair",
+                       style=theme.style("accent")))
+    console.print(Text(
+        "  then                     comodor whatsapp start --background",
+        style=theme.style("dim")))
+    console.print()
+    return 0
+
+
+def _wait_for_meta(heard: list[str], patience: float | None = None) -> bool:
+    """Whether the verification handshake actually arrived.
+
+    The default is read here rather than bound as a parameter default: bound,
+    it is captured when this module is imported, and nothing that changes
+    `VERIFY_PATIENCE` afterwards — a test, a setting — has any effect at all.
+    """
+    if patience is None:
+        patience = VERIFY_PATIENCE
+    deadline = time.time() + patience
+    while time.time() < deadline:
+        if any("verified by Meta" in line for line in heard):
+            return True
+        time.sleep(0.5)
+    return False
+
+
+def _unfinished(console, config: Config,
+                save: Callable[[Config], None]) -> int:
+    save(config)
+    console.print("\n  [dim]Saved what there was. `comodor whatsapp webhook` "
+                  "when you have an address.[/dim]\n")
+    return 0