handler-ai 0.1.0__py3-none-any.whl

handler_cli/automation_commands.py

@@ -0,0 +1,309 @@
+"""`handler automation …` — automations (docs/user/automations.md): when a
+session stops or at a time you set, handler runs your script in a sandbox (it may call the models
+you chose, what it writes is added to a knowledge note), one of your agents (its result goes to your
+inbox: `handler inbox`), or a route of one of your apps. Each is a folder of
+~/.config/handler-ai/automations/<name>/: edit its files in your editor.
+
+handler automation list                 every automation: on or off, when, last run, problems
+handler automation show NAME            what it may touch, its files, its problems, its next run
+handler automation new NAME --from EXAMPLE  copy an example handler ships (env-issues), off
+handler automation examples             the examples handler ships
+handler automation try NAME [--session ID|last]
+                                        run it now, on or off (one on a session that stopped:
+                                        on that session's whole conversation, default the one
+                                        that stopped last; a script's try adds nothing)
+handler automation enable NAME [--yes]  turn it on: shows what it may touch and asks first
+handler automation disable NAME         turn it off
+handler automation delete NAME [--yes]  delete it: its folder (its files) and its runs; asks first
+handler automation runs NAME            its runs, most recent first
+handler automation log RUN              a script run's output
+handler automation cancel RUN           stop a run
+"""
+
+import argparse
+import sys
+import time
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+from .client import ClientError, Daemon
+from .output import one_line, table
+
+WATCH_INTERVAL = 0.5
+
+
+def add_parser(sub: Any) -> None:
+    auto = sub.add_parser("automation", help="automations", description=__doc__,
+                          formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    a = auto.add_subparsers(dest="automation_cmd", required=True)
+    a.add_parser("list")
+    a.add_parser("examples")
+    new = a.add_parser("new")
+    new.add_argument("name")
+    new.add_argument("--from", dest="example", required=True, help="an example (env-issues)")
+    t = a.add_parser("try")
+    t.add_argument("name")
+    t.add_argument("--session", default="last", help="a session's id, or last (the default)")
+    e = a.add_parser("enable")
+    e.add_argument("name")
+    e.add_argument("--yes", action="store_true", help="do not ask")
+    rm = a.add_parser("delete")
+    rm.add_argument("name")
+    rm.add_argument("--yes", action="store_true", help="do not ask")
+    for name in ("show", "disable", "runs"):
+        a.add_parser(name).add_argument("name")
+    for name in ("log", "cancel"):
+        a.add_parser(name).add_argument("run")
+
+
+def sentence(definition: dict[str, Any] | None) -> str:
+    """When it runs, in words."""
+    if not definition:
+        return "-"
+    when = definition["when"]
+    if isinstance(when, dict):
+        if when.get("every"):
+            return f"every {when['every']}"
+        days = f" on {','.join(when['days'])}" if when.get("days") else ""
+        return f"at {when['at']}{days}"
+    only = definition.get("only") or {}
+    who = [f"project {', '.join(only['project'])}"] if only.get("project") else []
+    who += [f"agent {', '.join(only['agent'])}"] if only.get("agent") else []
+    return "when a session stops" + (f" ({'; '.join(who)})" if who else "")
+
+
+def what(definition: dict[str, Any] | None) -> str:
+    """What it runs, in a few words."""
+    if not definition:
+        return "-"
+    run = definition["run"]
+    if isinstance(run, str):
+        return "a script"
+    if "agent" in run:
+        return f"agent {run['agent']}" + (f" ({run['project']})" if run.get("project") else "")
+    return f"app {run['app']}"
+
+
+def last_run(view: dict[str, Any]) -> str:
+    run = view.get("lastRun")
+    if not run:
+        return "-"
+    return f"{run['state']} {run['createdAt'][:16].replace('T', ' ')}"
+
+
+def list_automations(d: Daemon, _: argparse.Namespace) -> int:
+    views = d.call("GET", "/v1/automations")
+    if not views:
+        print("no automation: handler automation new NAME --from env-issues")
+        return 0
+    rows = [["NAME", "", "WHEN", "RUNS", "LAST RUN", "PROBLEMS"]]
+    for v in views:
+        state = "on" if v.get("enabled") else "off"
+        problems = one_line("; ".join(v.get("problems") or []), 60) or "-"
+        definition = v.get("definition")
+        rows.append([v["name"], state, sentence(definition), what(definition), last_run(v),
+                     problems])  # fmt: skip
+    table(rows)
+    return 0
+
+
+def show(d: Daemon, args: argparse.Namespace) -> int:
+    v = d.call("GET", f"/v1/automations/{args.name}")
+    print(f"{v['name']}: {'on' if v.get('enabled') else 'off'}"
+          + (f" — {v['description']}" if v.get("description") else ""))  # fmt: skip
+    if permissions := v.get("permissions"):
+        print("What it does:")
+        for line in permissions:
+            print(f"  {line}")
+    for warning in v.get("warnings") or []:
+        print(f"warning: {warning}")
+    for problem in v.get("problems") or []:
+        print(f"problem: {problem}")
+    print(f"Files, in {v['directory']}:")
+    for file in v.get("files") or []:
+        print(f"  {file}")
+    if v.get("pending"):
+        capped = " (daily cap reached)" if v.get("capped") else ""
+        behind = f", behind {v['behind']} (one run at a time)" if v.get("behind") else ""
+        print(f"{v['pending']} run(s) waiting{capped}{behind}")
+    if v.get("nextAt"):
+        print(f"Next run: {when_at(v['nextAt'])}")
+    print(f"Last run: {last_run(v)}")
+    return 0
+
+
+def when_at(t: str) -> str:
+    """A time of the API (UTC) as the local time, to the minute."""
+    return datetime.fromisoformat(t).astimezone().strftime("%Y-%m-%d %H:%M")
+
+
+def examples(d: Daemon, _: argparse.Namespace) -> int:
+    table([["EXAMPLE", "DESCRIPTION"]] + [[e["name"], e.get("description") or ""]
+          for e in d.call("GET", "/v1/automation-examples")])  # fmt: skip
+    return 0
+
+
+def new(d: Daemon, args: argparse.Namespace) -> int:
+    v = d.call("POST", "/v1/automations", {"name": args.name, "from": args.example})
+    print(f"{args.name}: created, off, in {v['directory']}")
+    for problem in v.get("problems") or []:
+        print(f"problem: {problem}")
+    print(f"Edit its files, try it (handler automation try {args.name}), then turn it on "
+          f"(handler automation enable {args.name}).")  # fmt: skip
+    return 0
+
+
+def last_session(d: Daemon) -> str:
+    sessions = d.call("GET", "/v1/sessions")
+    stopped = [s for s in sessions if s["state"] == "stopped" and not s.get("input")]
+    if not stopped:
+        raise ClientError("no stopped session to try it on (--session ID)")
+    return max(stopped, key=lambda s: s["lastActivityAt"])["id"]
+
+
+def wait(d: Daemon, name: str, run: dict[str, Any]) -> dict[str, Any]:
+    while run["state"] in ("queued", "running"):
+        time.sleep(WATCH_INTERVAL)
+        run = d.call("GET", f"/v1/automations/{name}/runs/{run['id']}")
+    return run
+
+
+def run_for(run: dict[str, Any]) -> str:
+    """What a run was for: the session that stopped, or the schedule's slot (and those missed)."""
+    if run.get("sessionId"):
+        return f"session {run['sessionId']}, events {run['seqFrom']} to {run['seqTo']}"
+    if run.get("slot"):
+        missed = run.get("missed") or 0
+        return f"slot {when_at(run['slot'])}" + (f", {missed} missed before" if missed else "")
+    return "now"
+
+
+def describe_run(run: dict[str, Any]) -> list[str]:
+    llm = run.get("llm") or {}
+    lines = [f"{run['id']} {run['state']}{' (try)' if run.get('trial') else ''}: {run_for(run)}"]
+    if run.get("agentSessionId"):
+        lines.append(f"  the agent's session: {run['agentSessionId']}")
+    if run.get("error"):
+        lines.append(f"  error: {run['error']}")
+    if llm.get("calls"):
+        lines.append(f"  {llm['calls']} model call(s), {llm['inTokens']} tokens in, "
+                     f"{llm['outTokens']} out")  # fmt: skip
+    for appended in run.get("appended") or []:
+        verb = "would add" if run.get("trial") else "added"
+        lines.append(f"  {verb} {appended['bytes']} bytes to {appended['to']}")
+    return lines
+
+
+def try_it(d: Daemon, args: argparse.Namespace) -> int:
+    v = d.call("GET", f"/v1/automations/{args.name}")
+    if (v.get("definition") or {}).get("when") == "session.stopped":
+        session = last_session(d) if args.session == "last" else args.session
+        run = d.call("POST", f"/v1/automations/{args.name}/try", {"sessionId": session})
+        print(f"trying {args.name} on session {session} ({run['id']})…", file=sys.stderr)
+    else:
+        run = d.call("POST", f"/v1/automations/{args.name}/try", {})
+        print(f"trying {args.name} ({run['id']})…", file=sys.stderr)
+    run = wait(d, args.name, run)
+    print("\n".join(describe_run(run)))
+    if run.get("agentSessionId") and run["state"] == "succeeded":
+        output = d.call("GET", f"/v1/sessions/{run['agentSessionId']}").get("output") or {}
+        value = output.get("value") or {}
+        print(f"  {value.get('status')}: {value.get('summary')} (in your inbox: handler inbox)")
+    for appended in run.get("appended") or []:
+        print(f"\n--- {appended['to']} would get:\n{appended.get('text', '')}", end="")
+    if run["state"] != "succeeded":
+        print(f"(its output: handler automation log {run['id']})", file=sys.stderr)
+        return 1
+    return 0
+
+
+def enable(d: Daemon, args: argparse.Namespace) -> int:
+    v = d.call("GET", f"/v1/automations/{args.name}")
+    if v.get("problems"):
+        raise ClientError(f"{args.name} has problems: {'; '.join(v['problems'])}")
+    print(f"{args.name}, once on:")
+    for line in v.get("permissions") or []:
+        print(f"  {line}")
+    for warning in v.get("warnings") or []:
+        print(f"warning: {warning}")
+    if not args.yes and input("Turn it on? [y/N] ").strip().lower() != "y":
+        return 1
+    v = d.call("POST", f"/v1/automations/{args.name}/enable")
+    if v.get("nextAt"):
+        print(f"{args.name}: on, next run {when_at(v['nextAt'])}")
+    else:
+        print(f"{args.name}: on (sessions that stop from now on)")
+    return 0
+
+
+def disable(d: Daemon, args: argparse.Namespace) -> int:
+    d.call("POST", f"/v1/automations/{args.name}/disable")
+    print(f"{args.name}: off")
+    return 0
+
+
+def delete(d: Daemon, args: argparse.Namespace) -> int:
+    v = d.call("GET", f"/v1/automations/{args.name}")
+    count = len(d.call("GET", f"/v1/automations/{args.name}/runs"))
+    print(f"{args.name}: {'on' if v.get('enabled') else 'off'}; deleting it removes")
+    print(f"  its folder, with every file in it: {v['directory']}")
+    runs_of = f"{count} run{'' if count == 1 else 's'}"
+    print(f"  its {runs_of} and their logs (what it told your inbox stays)")
+    if v.get("enabled"):
+        print("  and stops it (a run in progress is cancelled)")
+    if not args.yes and input("Delete it? [y/N] ").strip().lower() != "y":
+        return 1
+    d.call("DELETE", f"/v1/automations/{args.name}")
+    print(f"{args.name}: deleted")
+    return 0
+
+
+def runs(d: Daemon, args: argparse.Namespace) -> int:
+    rows = [["RUN", "STATE", "FOR", "STARTED", "ADDED"]]
+    for run in d.call("GET", f"/v1/automations/{args.name}/runs"):
+        state = run["state"] + (" (try)" if run.get("trial") else "")
+        added = ", ".join(a["to"] for a in run.get("appended") or []) or "-"
+        rows.append([run["id"], state, run_for(run), when_at(run["createdAt"]), added])
+    table(rows)
+    return 0
+
+
+def find_run(d: Daemon, run_id: str) -> str:
+    """The automation `run_id` is a run of."""
+    for v in d.call("GET", "/v1/automations"):
+        if any(r["id"] == run_id for r in d.call("GET", f"/v1/automations/{v['name']}/runs")):
+            return v["name"]
+    raise ClientError(f"no run {run_id}")
+
+
+def log(d: Daemon, args: argparse.Namespace) -> int:
+    name = find_run(d, args.run)
+    print(d.text(f"/v1/automations/{name}/runs/{args.run}/log"), end="")
+    return 0
+
+
+def cancel(d: Daemon, args: argparse.Namespace) -> int:
+    name = find_run(d, args.run)
+    run = d.call("POST", f"/v1/automations/{name}/runs/{args.run}/cancel")
+    print("\n".join(describe_run(wait(d, name, run))))
+    return 0
+
+
+COMMANDS: dict[str, Callable[[Daemon, argparse.Namespace], int]] = {
+    "list": list_automations,
+    "show": show,
+    "examples": examples,
+    "new": new,
+    "try": try_it,
+    "enable": enable,
+    "disable": disable,
+    "runs": runs,
+    "log": log,
+    "cancel": cancel,
+    "delete": delete,
+}
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    return COMMANDS[args.automation_cmd](Daemon(), args)

handler_cli/bridge.py

@@ -0,0 +1,42 @@
+"""`handler acp`: bridge stdio (an editor such as Zed, or any ACP client) to an agent's ACP
+WebSocket.
+
+The editor talks NDJSON on our stdin/stdout; handlerd applies the policy (P1-P7) and runs the agent
+in its sandbox. One JSON-RPC message per line one way, per frame the other way.
+"""
+
+import sys
+import threading
+
+from websockets.exceptions import ConnectionClosed
+from websockets.sync.client import ClientConnection, connect
+from websockets.typing import Subprotocol
+
+from handler_contracts import ACP_SUBPROTOCOL, BEARER_SUBPROTOCOL_PREFIX, AcpCloseCode
+
+
+def _stdin_to_ws(ws: ClientConnection) -> None:
+    try:
+        for line in sys.stdin.buffer:
+            if line.strip():
+                ws.send(line.decode().rstrip("\n"))
+    except ConnectionClosed:
+        return
+    ws.close()  # the editor closed our stdin: end the connection (the sandbox stops)
+
+
+def run_bridge(acp_url: str, token: str) -> int:
+    protocols = [Subprotocol(ACP_SUBPROTOCOL), Subprotocol(BEARER_SUBPROTOCOL_PREFIX + token)]
+    with connect(acp_url, subprotocols=protocols, max_size=None) as ws:
+        threading.Thread(target=_stdin_to_ws, args=(ws,), daemon=True).start()
+        try:
+            for message in ws:
+                text = message if isinstance(message, str) else message.decode()
+                sys.stdout.write(text + "\n")
+                sys.stdout.flush()
+        except ConnectionClosed:
+            pass
+    if ws.close_code in (None, AcpCloseCode.NORMAL):
+        return 0
+    print(f"handler acp: connection closed ({ws.close_code}) {ws.close_reason}", file=sys.stderr)
+    return 1

handler_cli/cli.py

@@ -0,0 +1,326 @@
+"""handler — run coding agents in sandboxes on your machine. Each command talks to handlerd,
+the daemon that keeps the agents running (`handler setup` installs it).
+
+Working with agents:
+    handler run [AGENT|ACCOUNT|PROVIDER] [-p REQUEST] [agent options] [--remote] [--detach]
+                [--anyway]                   a session in the current directory, in the terminal
+                                             (also shown in the web UI): the project's agent in a
+                                             project's folder, else ad hoc (`handler run -h`)
+    handler attach [SESSION] [--stdio]       back to a session: a running one is joined, a stopped
+                                             one resumed
+    handler terminal AGENT|ACCOUNT|PROVIDER [FOLDER] [agent options] [--anyway] [-- ARGS …]
+                                             the harness's own terminal UI (e.g. Claude Code's) in
+                                             its sandbox, ARGS given to it; not a session: one
+                                             sandbox, gone when it exits
+    handler acp AGENT|ACCOUNT|PROVIDER [FOLDER] [agent options] [--anyway]
+                                             ACP on stdio, for editors (e.g. Zed): an agent of the
+                                             folder's project (a session shown in the web UI), else
+                                             an account or a provider (one sandbox for this
+                                             connection)
+
+What exists (`handler NOUN -h` for each):
+    handler session list | show | stop | share   sessions
+    handler agent list | show | rm | network     agents, their network (log-only, enforce)
+    handler project list | show                  projects (created and edited in the web UI)
+    handler account list | add | token | login | import | rm
+                                                 subscriptions and their login
+    handler provider list | templates | add | rm API keys and local model servers
+    handler secret list | set | rm               the secret store
+    handler addon list | catalog | add | rm      addons an agent can get
+    handler binding list                         addons with their settings and secrets
+    handler knowledge list                       knowledge folders an agent can get
+    handler image list | rebuild                 the images agents run in
+    handler app …                                mini apps: register, deploy, open
+    handler automation …                         when a session stops or at a time, run a script,
+                                                 an agent or an app's route
+    handler inbox                                what handler told you: apps' notifications,
+                                                 automations' results and failures
+
+Handler itself:
+    handler setup [--no-build] [--yes]           after installing: start handlerd as a service,
+                                                 check this machine, build the images
+    handler daemon status | install | uninstall | log
+                                                 handlerd as a systemd user service
+    handler ui [--print]                         open the web UI (token passed in the URL fragment)
+
+FOLDER defaults to the current directory, inside one of the work folders (set in the web UI,
+Settings → Folders). A knowledge FOLDER is a path relative to the knowledge root (see `handler
+knowledge list`; set in the web UI), or an absolute path inside it; the agent sees it read-only at
+/knowledge/<folder name>. Outside projects the sandbox starts from a preset: filtered network,
+enforced (--log-only lets every host through and logs it, to learn which it needs), strict
+confinement, permissions bypass. A flag that widens it (--network open, --log-only, --containers)
+is your confirmation: handler says on stderr what it gives the agent.
+--allow adds hosts to a filtered agent's (on top of those its account or provider and its
+addons require). --permissions sets the agent's starting mode: ask (you answer each request),
+accept-edits (file edits allowed) or bypass (unsupervised); the session can change it.
+--containers lets the agent run podman itself (nested confinement). --display gives the agent's
+sandbox your Wayland display, e.g. to watch the browser of the playwright addon, and its
+clipboard: pasting images in `handler terminal` needs it (the agent can then read what you copy);
+nothing else of your desktop.
+
+An ACCOUNT runs its own harness; a PROVIDER runs the harness --harness names (or the only one
+that speaks its protocol). --model picks the model (default: the harness's or the provider's).
+The account or provider and the model are for this time only: never saved to the agent.
+
+Outside projects, the agent is the one of the folder and its --name (none: the unnamed one):
+the same command in the same folder always gives the same agent, made with the flags typed
+the first time. In a project's folder (or below), `run`, `acp` and `terminal` use the project's
+agent named AGENT, or the one using that ACCOUNT or PROVIDER (default agent first); an account
+or provider none of its agents uses runs the default agent, unless it is not made for the
+project's context (refused; --anyway runs it there outside the project). A flag that differs
+from the agent's settings is never ignored: handler says what differs and asks "Save this to the
+agent?" (yes saves it, no starts nothing); without a terminal, --save saves it, else it is
+refused. Something to try once is another agent: --name NAME (outside projects).
+Elsewhere, `handler run` without a name takes the only account or provider ready.
+The terminal client is built in; HANDLER_ACP_CLIENT names another one (see `handler run -h`).
+"""
+
+import argparse
+import os
+import sys
+import webbrowser
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+from urllib.parse import urlencode
+
+from . import (
+    account_commands,
+    addon_commands,
+    agent_commands,
+    app_commands,
+    automation_commands,
+    bridge,
+    daemon_commands,
+    image_commands,
+    inbox_commands,
+    project_commands,
+    provider_commands,
+    secret_commands,
+    session_commands,
+    setup,
+    terminal_client,
+)
+from .client import ClientError, Daemon, base_url, read_token
+from .output import table
+from .session_bridge import run_session_bridge
+
+
+def add_agent_options(s: argparse.ArgumentParser) -> None:
+    s.add_argument(
+        "--harness",
+        help="the harness, for a provider (an account has its own); in a project's folder: "
+        "which of the agent's models",
+    )
+    s.add_argument(
+        "--model",
+        help="the model (default: the harness's or the provider's); in a project's folder: "
+        "which of the agent's models",
+    )
+    s.add_argument("--name", help="a name, e.g. the use case (several per folder are fine)")
+    s.add_argument("--network", choices=["none", "filtered", "open"], help="default: filtered")
+    s.add_argument(
+        "--log-only",
+        action="store_true",
+        help="filtered: let every host through and log it, to learn which it needs "
+        "(default: deny what is not allowed)",
+    )
+    s.add_argument(
+        "--allow",
+        action="append",
+        metavar="HOST:PORT",
+        help="a host to allow (filtered network), on top of the required ones; repeatable",
+    )
+    s.add_argument(
+        "--binding",
+        action="append",
+        metavar="NAME",
+        help="a binding (addon + instance + credentials) to give the agent; repeatable",
+    )
+    s.add_argument(
+        "--knowledge",
+        action="append",
+        metavar="FOLDER",
+        help="a folder of the knowledge root, mounted read-only at /knowledge/<name>; repeatable",
+    )
+    s.add_argument(
+        "--permissions",
+        choices=["ask", "accept-edits", "bypass"],
+        help="the agent's starting permission mode (default: bypass)",
+    )
+    s.add_argument(
+        "--containers",
+        action="store_true",
+        help="let the agent run containers itself (podman in podman)",
+    )
+    s.add_argument(
+        "--display",
+        action="store_true",
+        help="give the sandbox your Wayland display and clipboard (watch a browser, paste images)",
+    )
+    s.add_argument(
+        "--save",
+        action="store_true",
+        help="save the flags that differ from the agent's settings to it, without being asked "
+        "(needed without a terminal)",
+    )
+
+
+def acp(d: Daemon, args: argparse.Namespace) -> int:
+    """An agent of the folder's project: a daemon session (shown in the web UI) as a stdio agent.
+    Otherwise (or --anyway) an account or provider: one sandbox for this connection only."""
+    found = session_commands.project_agent(d, args.access, os.path.abspath(args.scope), args)
+    if found is not None:
+        agent, model = found
+        body: dict[str, Any] = {"agentId": agent["id"]}
+        if model is not None:
+            body["model"] = session_commands.access_of(model)
+        return run_session_bridge(d, d.call("POST", "/v1/sessions", body))
+    agent, model = session_commands.open_ad_hoc(d, args)
+    return bridge.run_bridge(f"{agent['acpUrl']}?{urlencode(model)}", d.token)
+
+
+def terminal(d: Daemon, args: argparse.Namespace) -> int:
+    """D.16: an agent of the folder's project, else (or --anyway) an account or provider; one
+    sandbox for this terminal."""
+    found = session_commands.project_agent(d, args.access, os.path.abspath(args.scope), args)
+    agent, model = found if found is not None else session_commands.open_ad_hoc(d, args)
+    model = model or agent["models"][0]
+    print(terminal_identity(d, model), file=sys.stderr)
+    return terminal_client.run(d, agent["id"], args.args, session_commands.access_of(model))
+
+
+def terminal_identity(d: Daemon, model: dict[str, Any]) -> str:
+    """Who the harness runs as (the model of this terminal), from handler's own files: the harness's
+    terminal cannot tell (a token login says neither the email nor the plan)."""
+    if provider := model.get("provider"):
+        harness = model["harness"]
+        return f"handler: {harness} · provider {provider} (its endpoint and key, no subscription)"
+    name = model.get("account")
+    account = next((a for a in d.call("GET", "/v1/accounts") if a["name"] == name), {})
+    harness = model.get("harness") or account.get("harness")  # a model it does not list: none
+    described = f" ({account['description']})" if account.get("description") else ""
+    plan = account.get("plan")
+    subscription = f"{plan} subscription" if plan else "subscription, plan not set in the account"
+    return f"handler: {harness} · account {name}{described} · {subscription}"
+
+
+def print_knowledge(d: Daemon) -> None:
+    listing = d.call("GET", "/v1/knowledge")
+    if not listing["exists"]:
+        print(f"no knowledge root: {listing['root']} does not exist (set it in the web UI)")
+        return
+    print(f"knowledge root: {listing['root']} ({listing['source']})")
+    for folder in listing["folders"]:
+        print(f"  {folder}")
+
+
+def print_bindings(d: Daemon) -> None:
+    rows = [["NAME", "ADDON", "SETTINGS", "SECRETS", "ERROR"]]
+    for b in d.call("GET", "/v1/bindings"):
+        settings = ", ".join(f"{k}={v}" for k, v in b.get("settings", {}).items())
+        rows.append(
+            [
+                b["name"],
+                b.get("addon", "?"),
+                settings or "-",
+                ", ".join(b.get("secrets", [])) or "-",
+                b.get("error", "")[:80],
+            ]
+        )
+    table(rows)
+
+
+def open_ui(*, print_only: bool) -> int:
+    """The token travels in the URL fragment: browsers never send it to the server."""
+    url = f"{base_url()}/#token={read_token()}"
+    print(url)
+    if not print_only:
+        webbrowser.open(url)
+    return 0
+
+
+def installed_version() -> str:
+    """This client's version, read without handlerd (a bug report needs it when handlerd is
+    down): the `handler-ai` wheel users install, else this package in a checkout."""
+    for distribution in ("handler-ai", "handler-cli"):
+        try:
+            return version(distribution)
+        except PackageNotFoundError:
+            pass
+    return "unknown"
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="handler", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    p.add_argument("--version", action="version", version=f"handler {installed_version()}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    session_commands.add_parsers(sub, add_agent_options)
+    for name in ("terminal", "acp"):
+        s = sub.add_parser(name)
+        s.add_argument("access", metavar="AGENT|ACCOUNT|PROVIDER")
+        s.add_argument("scope", nargs="?", default=".", metavar="FOLDER")
+        add_agent_options(s)
+        session_commands.add_anyway_option(s)
+    for module in NOUNS.values():
+        module.add_parser(sub)
+    for name, help_text in (("binding", "addons with their settings and secrets"),
+                            ("knowledge", "knowledge folders")):  # fmt: skip
+        noun = sub.add_parser(name, help=help_text)
+        noun.add_subparsers(dest=f"{name}_cmd", required=True).add_parser("list")
+    sub.add_parser("ui").add_argument("--print", action="store_true", help="only print the URL")
+    return p
+
+
+# nouns whose module parses and runs its own subcommands
+NOUNS: dict[str, Any] = {
+    "agent": agent_commands,
+    "project": project_commands,
+    "account": account_commands,
+    "provider": provider_commands,
+    "secret": secret_commands,
+    "addon": addon_commands,
+    "image": image_commands,
+    "app": app_commands,
+    "automation": automation_commands,
+    "inbox": inbox_commands,
+    "daemon": daemon_commands,
+    "setup": setup,
+}
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    if args.cmd in NOUNS:
+        return NOUNS[args.cmd].dispatch(args)
+    if args.cmd == "ui":
+        return open_ui(print_only=args.print)
+    d = Daemon()
+    if args.cmd == "binding":
+        print_bindings(d)
+    elif args.cmd == "knowledge":
+        print_knowledge(d)
+    elif args.cmd in ("acp", "terminal"):
+        return (acp if args.cmd == "acp" else terminal)(d, args)
+    else:
+        return session_commands.dispatch(d, args)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    rest: list[str] = []
+    if argv[:1] == ["terminal"] and "--" in argv:  # what follows `--` is the harness's
+        at = argv.index("--")
+        argv, rest = argv[:at], argv[at + 1 :]
+    args = parser().parse_args(argv)
+    args.args = rest
+    try:
+        return dispatch(args)
+    except ClientError as e:
+        print(f"handler: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())