handler-ai 0.1.0__py3-none-any.whl

handler_cli/addon_commands.py

@@ -0,0 +1,128 @@
+"""`handler addon …` — addons (contract G.5): a tool for the agent's sandbox (Playwright's browser,
+the Shopify CLI) with the hosts, secrets and skills it needs. An agent gets one through a binding
+(`handler binding list`).
+
+handler addon list                   the installed addons: where from, commands, image, the settings
+                                     and secrets they need, errors, updates
+handler addon catalog                the addons handler ships, installed or not
+handler addon add NAME|FOLDER|URL [--yes]
+                                     what it brings (its hosts, secrets, commands, MCP server,
+                                     skills), then, once you agree, install it and build its image:
+                                     NAME from the catalog, a FOLDER, an https:// .tar.gz archive
+handler addon rm NAME                an installed addon (refused while a binding uses it)
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import image_commands
+from .client import Daemon
+from .output import table
+
+
+def add_parser(sub: Any) -> None:
+    addon = sub.add_parser("addon", help="install and remove addons", description=__doc__,
+                           formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    s = addon.add_subparsers(dest="addon_cmd", required=True)
+    s.add_parser("list")
+    s.add_parser("catalog")
+    add = s.add_parser("add")
+    add.add_argument("source", metavar="NAME|FOLDER|URL")
+    add.add_argument("--yes", action="store_true", help="install without asking")
+    s.add_parser("rm").add_argument("name")
+
+
+def source(arg: str) -> str:
+    """What the API calls the source: catalog:NAME, an absolute folder path, or the URL."""
+    if arg.startswith(("https://", "http://")):
+        return arg
+    if "/" in arg or arg.startswith(".") or Path(arg).is_dir():
+        return str(Path(arg).resolve())
+    return f"catalog:{arg}"
+
+
+def describe(p: dict[str, Any]) -> str:
+    """The trust screen, as text: everything the addon would bring."""
+    lines = [f"{p['name']}: {p.get('description') or ''}".rstrip(": "), f"  from    {p['source']}"]
+    if replaces := p.get("replaces"):
+        lines.append(f"  replaces the {replaces} addon '{p['name']}'")
+    rows = [
+        ("hosts", ", ".join(p.get("egress", []))),
+        ("secrets", ", ".join(s["name"] for s in p.get("secretSlots", []))),
+        ("settings", ", ".join(s["name"] for s in p.get("settings", []))),
+        ("env", ", ".join(p.get("env", []))),
+        ("commands", ", ".join(p.get("commands", []))),
+        ("MCP", " ".join(p.get("mcp") or [])),
+        ("skills", ", ".join(p.get("skills", []))),
+    ]
+    lines += [f"  {k:<8}{v}" for k, v in rows if v]
+    if image := p.get("image"):
+        lines.append(f"  image   {image}: its Containerfile runs code on this machine when built")
+    return "\n".join(lines)
+
+
+def dispatch(args: argparse.Namespace) -> int:  # noqa: PLR0911 — one branch per subcommand
+    d = Daemon()
+    if args.addon_cmd == "list":
+        print_addons(d)
+        return 0
+    if args.addon_cmd == "catalog":
+        rows = [["NAME", "INSTALLED", "DESCRIPTION"]]
+        for e in d.call("GET", "/v1/addon-catalog"):
+            rows.append([e["name"], "yes" if e["installed"] else "-", e.get("description", "")])
+        table(rows)
+        return 0
+    if args.addon_cmd == "rm":
+        d.call("DELETE", f"/v1/addons/{args.name}")
+        print(f"removed {args.name}")
+        return 0
+    seen = d.call("POST", "/v1/addons/preview", {"source": source(args.source)})
+    print(describe(seen))
+    if not args.yes:
+        if not sys.stdin.isatty():
+            print("not installed: run again with --yes to install it")
+            return 1
+        if input("\nInstall it? [y/N] ").strip().lower() not in ("y", "yes"):
+            return 1
+    installed = d.call(
+        "POST", "/v1/addons/install", {"source": seen["source"], "digest": seen["digest"]}
+    )
+    print(f"installed {installed['addon']['name']} in {installed['addon']['directory']}")
+    if build := installed.get("build"):
+        return image_commands.watch(d, build)
+    if seen.get("image"):
+        print(
+            "another build is running: build it later with "
+            f"`handler image rebuild addon:{seen['name']}`"
+        )
+    return 0
+
+
+def print_addons(d: Daemon) -> None:
+    rows = [["NAME", "FROM", "COMMANDS", "VERSION", "BUILT", "SLOTS", "ERROR"]]
+    for a in d.call("GET", "/v1/addons"):
+        if a.get("image"):
+            version = a.get("version", "-") if a["imagePresent"] else "not built"
+        else:
+            version = "(no image)"
+        slots = [
+            *(s["name"] for s in a.get("settings", [])),
+            *(f"{s['name']} (secret)" for s in a.get("secretSlots", [])),
+        ]
+        origin = "built-in" if a.get("builtin") else a.get("source", "yours")
+        if a.get("updateAvailable"):
+            origin += " (update: handler addon add " + a["name"] + ")"
+        rows.append(
+            [
+                a["name"],
+                origin,
+                ", ".join(a.get("commands", [])) or "-",
+                version,
+                a.get("builtAt", "-")[:16].replace("T", " "),
+                ", ".join(slots) or "-",
+                a.get("error", "")[:80],
+            ]
+        )
+    table(rows)

handler_cli/agent_commands.py

@@ -0,0 +1,139 @@
+"""`handler agent …` — every agent, of projects and outside them (contract D.1, D.8). Agents of
+projects are created and edited in the web UI; agents outside projects are made by `handler run`,
+`terminal` and `acp` in a folder.
+
+handler agent list                   every agent, most recently used first, with its id
+handler agent show ID                its settings, models, folder and live sandboxes
+handler agent rm ID                  delete an agent outside projects (stops its sandboxes)
+handler agent network ID [log-only|enforce]
+                                     its network mode and recent connections (allowed, denied,
+                                     unlisted: let through in log-only, enforcing would deny); with
+                                     a mode, switch a filtered agent to it, live (log-only: every
+                                     host goes through and is logged, to learn which it needs)
+"""
+
+import argparse
+from typing import Any
+
+from .client import Daemon
+from .output import table
+
+
+def add_parser(sub: Any) -> None:
+    agent = sub.add_parser("agent", help="agents", description=__doc__,
+                           formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    a = agent.add_subparsers(dest="agent_cmd", required=True)
+    a.add_parser("list")
+    a.add_parser("show").add_argument("id")
+    a.add_parser("rm").add_argument("id")
+    network = a.add_parser("network")
+    network.add_argument("id")
+    network.add_argument("mode", nargs="?", choices=["log-only", "enforce"])
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    d = Daemon()
+    if args.agent_cmd == "list":
+        print_agents(d)
+    elif args.agent_cmd == "show":
+        show(d, d.call("GET", f"/v1/agents/{args.id}"))
+    elif args.agent_cmd == "rm":
+        d.call("DELETE", f"/v1/agents/{args.id}")
+        print(f"{args.id}: removed")
+    elif args.mode:
+        w = d.call("PATCH", f"/v1/agents/{args.id}", {"egress": args.mode})
+        print(f"agent {w['id']}: network {network_mode(w)}")
+    else:
+        print_network(d, d.call("GET", f"/v1/agents/{args.id}"))
+    return 0
+
+
+def print_agents(d: Daemon) -> None:
+    projects = {p["id"]: p["name"] for p in d.call("GET", "/v1/projects")}
+    rows = [["ID", "PROJECT", "NAME", "RUNS", "SETTINGS", "LIVE", "FOLDER"]]
+    listed = d.call("GET", "/v1/agents")
+    listed.sort(key=lambda a: a.get("lastUsedAt") or a["createdAt"], reverse=True)
+    for a in listed:
+        rows.append(
+            [
+                a["id"],
+                projects.get(a.get("projectId") or "", "(ad hoc)"),
+                (a.get("name") or "-") + (f" (built-in {a['origin']})" if a.get("origin") else ""),
+                runs(a),
+                describe_agent(a, runs_too=False),
+                str(len(a["connections"])),
+                a.get("scope") or "(a folder per session)",
+            ]
+        )
+    table(rows)
+
+
+def show(d: Daemon, a: dict[str, Any]) -> None:
+    projects = {p["id"]: p["name"] for p in d.call("GET", "/v1/projects")}
+    project = projects.get(a.get("projectId") or "", "ad hoc")
+    print(f"{a.get('name') or a['models'][0]['harness']} · {a['id']} · {project}")
+    if a.get("description"):
+        print(f"  {a['description']}")
+    print(f"  folder       {a.get('scope') or '(a folder per session)'}")
+    for i, m in enumerate(a["models"]):
+        print(f"  {'runs' if i == 0 else '':<12} {model_label(m)}")
+    print(f"  network      {network_mode(a)}")
+    if a.get("allow"):
+        print(f"  its hosts    {', '.join(a['allow'])}")
+    print(f"  permissions  {a['permissions']}")
+    for key, label in (("bindings", "bindings"), ("knowledge", "knowledge"), ("skills", "skills")):
+        if a.get(key):
+            print(f"  {label:<12} {', '.join(a[key])}")
+    if a.get("confinement", "strict") != "strict":
+        print(f"  containers   {'yes' if a['confinement'] == 'nested' else a['confinement']}")
+    if a.get("display"):
+        print("  display      yes")
+    print(f"  live         {len(a['connections'])} sandbox(es)")
+
+
+def network_mode(a: dict[str, Any]) -> str:
+    """`filtered, log-only` / `filtered, enforce` / `open` / `none`."""
+    if a["network"] != "filtered":
+        return a["network"]
+    return f"filtered, {a.get('egress') or 'enforce'}"
+
+
+def print_network(d: Daemon, a: dict[str, Any]) -> None:
+    print(f"network {network_mode(a)}" + (f" + {', '.join(a['allow'])}" if a.get("allow") else ""))
+    events = d.call("GET", f"/v1/agents/{a['id']}/egress-events")
+    if not events:
+        print("no connection yet")
+        return
+    rows = [["TIME", "DECISION", "HOST", "CONNECTION"]]
+    rows += [[e["t"][11:19], e["decision"], e["host"], e["connection"]] for e in events]
+    table(rows)
+
+
+def runs(w: dict[str, Any]) -> str:
+    """Its models, the default first: `claude-code · account claude-pro`, `codex · provider
+    llamacpp · qwen3`."""
+    return " | ".join(model_label(m) for m in w["models"])
+
+
+def model_label(m: dict[str, Any]) -> str:
+    access = f"account {m['account']}" if m.get("account") else f"provider {m.get('provider')}"
+    return " · ".join([m["harness"], access, *([m["model"]] if m.get("model") else [])])
+
+
+def describe_agent(w: dict[str, Any], *, runs_too: bool = True) -> str:
+    """Its settings in one line, the defaults left out: `runs=… network=filtered/log-only
+    +2 hosts bindings=… knowledge=… containers display`."""
+    network = w["network"] + (f"/{w['egress']}" if w.get("egress") == "log-only" else "")
+    parts = [f"runs={runs(w)}"] if runs_too else []
+    parts.append(f"network={network}" + (f" +{len(w['allow'])} hosts" if w.get("allow") else ""))
+    if w["permissions"] != "bypass":
+        parts.append(f"permissions={w['permissions']}")
+    if w.get("bindings"):
+        parts.append(f"bindings={','.join(w['bindings'])}")
+    if w.get("knowledge"):
+        parts.append(f"knowledge={','.join(w['knowledge'])}")
+    if w.get("confinement", "strict") != "strict":
+        parts.append("containers" if w["confinement"] == "nested" else w["confinement"])
+    if w.get("display"):
+        parts.append("display")
+    return "  ".join(parts)

handler_cli/app_commands.py

@@ -0,0 +1,175 @@
+"""`handler app …` — mini apps (contract H, docs/dev/design/miniapps.md): small web apps written by
+an agent, run by handlerd on demand, each at its own origin (http://<name>.localhost:<port>/).
+
+handler app list                   registered apps, their versions and state
+handler app add [DIR]              register the app whose app.toml is in DIR (default: here)
+handler app deploy NAME [--yes]    install what its folder holds now: tests, health check on a
+                                   copy of the data, then switch (asks first when it may reach
+                                   more than before)
+handler app rollback NAME          back to the previous version and its data as it was then
+handler app open NAME [--print]    open it in its own window (a one-time link): Firefox with
+                                   the handler-apps profile, else Chromium's app mode, else the
+                                   default browser (HANDLER_APP_BROWSER=firefox|chromium|default)
+handler app shortcut NAME KEYS|--none  the GNOME keyboard shortcut that opens it, e.g. "<Super>n"
+handler app stop NAME              stop its backend now (it starts again when used)
+handler app log NAME               its last deploys and its backend's output
+handler app secret NAME SECRET [--unset]
+                                   set a secret the app declares (asked for, or read from stdin);
+                                   the backend restarts with it
+handler app rm NAME                unregister it; its data folder is kept
+"""
+
+import argparse
+import getpass
+import os
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from . import app_window
+from .client import ClientError, Daemon
+from .output import table
+
+
+def add_parser(sub: Any) -> None:
+    app = sub.add_parser("app", help="mini apps", description=__doc__,
+                         formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    a = app.add_subparsers(dest="app_cmd", required=True)
+    a.add_parser("list")
+    a.add_parser("add").add_argument("dir", nargs="?", default=".")
+    d = a.add_parser("deploy")
+    d.add_argument("name")
+    d.add_argument("--yes", action="store_true", help="do not ask about new needs")
+    o = a.add_parser("open")
+    o.add_argument("name")
+    o.add_argument("--print", action="store_true", help="only print the link")
+    sc = a.add_parser("shortcut")
+    sc.add_argument("name")
+    keys = sc.add_mutually_exclusive_group(required=True)
+    keys.add_argument("keys", nargs="?", help='GNOME accelerator, e.g. "<Super>n"')
+    keys.add_argument("--none", action="store_true", help="remove its shortcut")
+    sec = a.add_parser("secret")
+    sec.add_argument("name")
+    sec.add_argument("secret")
+    sec.add_argument("--unset", action="store_true")
+    for name in ("rollback", "stop", "log", "rm"):
+        a.add_parser(name).add_argument("name")
+
+
+def describe(app: dict[str, Any]) -> str:
+    current = app.get("current")
+    installed = current["version"] if current else "not deployed"
+    lines = [f"{app['name']} {installed} ({app['state']}) — {app['url']}"]
+    source = app["source"]
+    if source.get("error"):
+        lines.append(f"  source: {source['error']}")
+    elif not current or source.get("version") != current["version"]:
+        lines.append(f"  source: {source.get('version')} ready to deploy")
+    if missing := [s["name"] for s in app.get("secrets", []) if not s["set"]]:
+        lines.append(f"  secrets not set: {', '.join(missing)} (handler app secret)")
+    if app.get("shortcut"):
+        lines.append(f"  shortcut: {app['shortcut']}")
+    if app.get("error"):
+        lines.append(f"  error: {app['error']}")
+    return "\n".join(lines)
+
+
+def list_apps(d: Daemon, _: argparse.Namespace) -> int:
+    rows = [["NAME", "VERSION", "STATE", "SOURCE", "URL"]]
+    for app in d.call("GET", "/v1/apps"):
+        current = app.get("current")
+        source = app["source"].get("version") or "invalid"
+        rows.append(
+            [
+                app["name"],
+                current["version"] if current else "-",
+                app["state"],
+                source if not current or source != current["version"] else "=",
+                app["url"],
+            ]
+        )
+    table(rows)
+    return 0
+
+
+def add(d: Daemon, args: argparse.Namespace) -> int:
+    print(describe(d.call("POST", "/v1/apps", {"sourceDir": os.path.abspath(args.dir)})))
+    return 0
+
+
+def deploy(d: Daemon, args: argparse.Namespace) -> int:
+    app = d.call("GET", f"/v1/apps/{args.name}")
+    if app["source"].get("error"):
+        raise ClientError(app["source"]["error"])
+    if (added := app["source"].get("addedNeeds")) and not args.yes:
+        print(f"{args.name} {app['source']['version']} may reach more than before:")
+        for need in added:
+            print(f"  + {need}")
+        if input("Deploy? [y/N] ").strip().lower() != "y":
+            return 1
+    print(f"deploying {args.name} {app['source']['version']} (tests, health check)…")
+    print(describe(d.call("POST", f"/v1/apps/{args.name}/deploy")))
+    return 0
+
+
+def open_app(d: Daemon, args: argparse.Namespace) -> int:
+    url = d.call("POST", f"/v1/apps/{args.name}/open")["url"]
+    print(url)
+    if not args.print:
+        app_window.open_window(url)
+    return 0
+
+
+def shortcut(d: Daemon, args: argparse.Namespace) -> int:
+    keys = None if args.none else args.keys
+    app = d.call("PUT", f"/v1/apps/{args.name}/shortcut", {"shortcut": keys})
+    print(f"{args.name}: {app.get('shortcut') or 'no shortcut'}")
+    return 0
+
+
+def log(d: Daemon, args: argparse.Namespace) -> int:
+    print(d.call("GET", f"/v1/apps/{args.name}/log")["text"], end="")
+    return 0
+
+
+def secret(d: Daemon, args: argparse.Namespace) -> int:
+    path = f"/v1/apps/{args.name}/secrets/{args.secret}"
+    if args.unset:
+        app = d.call("DELETE", path)
+    else:
+        prompt = f"{args.secret} for {args.name}: "
+        value = getpass.getpass(prompt) if sys.stdin.isatty() else sys.stdin.readline()
+        app = d.call("PUT", path, {"value": value.strip()})
+    state = {s["name"]: s["set"] for s in app.get("secrets", [])}
+    print(f"{args.secret}: {'set' if state.get(args.secret) else 'not set'}")
+    return 0
+
+
+def remove(d: Daemon, args: argparse.Namespace) -> int:
+    d.call("DELETE", f"/v1/apps/{args.name}")
+    print(f"{args.name}: removed (its data folder is kept)")
+    return 0
+
+
+def action(d: Daemon, args: argparse.Namespace) -> int:
+    """rollback, stop: a POST that answers the app."""
+    print(describe(d.call("POST", f"/v1/apps/{args.name}/{args.app_cmd}")))
+    return 0
+
+
+COMMANDS: dict[str, Callable[[Daemon, argparse.Namespace], int]] = {
+    "list": list_apps,
+    "add": add,
+    "deploy": deploy,
+    "open": open_app,
+    "log": log,
+    "secret": secret,
+    "shortcut": shortcut,
+    "rm": remove,
+    "rollback": action,
+    "stop": action,
+}
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    return COMMANDS[args.app_cmd](Daemon(), args)

handler_cli/app_window.py

@@ -0,0 +1,85 @@
+"""Opening a mini app in its own window (docs/dev/design/miniapps.md §5.1).
+
+Firefox first (a dedicated profile, `handler-apps`: apps' cookies and storage stay out of normal
+browsing, and its toolbars are hidden, since Firefox has no `--app` mode), then Chromium's app
+mode, then the default browser. `HANDLER_APP_BROWSER` (firefox · chromium · default) forces one.
+"""
+
+import os
+import shutil
+import subprocess
+import webbrowser
+from pathlib import Path
+
+# the window's app id: GNOME groups app windows apart from the browser
+WINDOW_CLASS = "handler-apps"
+
+USER_JS = """\
+// handler: the profile mini apps open in (handler app open). Rewritten by handler.
+user_pref("toolkit.legacyUserProfileCustomizations.stylesheets", true);
+user_pref("browser.shell.checkDefaultBrowser", false);
+user_pref("browser.startup.homepage_override.mstone", "ignore");
+user_pref("browser.aboutwelcome.enabled", false);
+user_pref("browser.startup.page", 0);
+user_pref("browser.sessionstore.resume_from_crash", false);
+user_pref("browser.tabs.warnOnClose", false);
+user_pref("datareporting.policy.dataSubmissionEnabled", false);
+user_pref("toolkit.telemetry.reportingpolicy.firstRun", false);
+"""
+
+USER_CHROME = """\
+/* handler: an app window, not a browser window. Rewritten by handler. */
+#TabsToolbar, #nav-bar, #PersonalToolbar, #titlebar { visibility: collapse !important; }
+"""
+
+CHROMIUMS = ("chromium", "chromium-browser", "google-chrome", "google-chrome-stable")
+
+
+def profiles_dir() -> Path:
+    xdg = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    return Path(os.environ.get("HANDLER_DATA_DIR", xdg / "handler-ai"))
+
+
+def firefox_profile(root: Path) -> Path:
+    """The `handler-apps` Firefox profile, created or refreshed (only handler's two files)."""
+    profile = root / "firefox-apps"
+    (profile / "chrome").mkdir(parents=True, exist_ok=True)
+    (profile / "user.js").write_text(USER_JS)
+    (profile / "chrome" / "userChrome.css").write_text(USER_CHROME)
+    return profile
+
+
+def argv(url: str, browser: str, root: Path) -> list[str] | None:
+    """The command opening `url` in an app window; None: the default browser."""
+    if browser == "firefox" and (firefox := shutil.which("firefox")):
+        profile = firefox_profile(root)
+        return [firefox, "--profile", str(profile), "--name", WINDOW_CLASS, "--new-window", url]
+    if browser == "chromium" and (
+        chromium := next(filter(None, map(shutil.which, CHROMIUMS)), None)
+    ):
+        data = root / "chromium-apps"
+        return [chromium, f"--user-data-dir={data}", f"--class={WINDOW_CLASS}", f"--app={url}"]
+    return None
+
+
+def choose() -> str:
+    forced = os.environ.get("HANDLER_APP_BROWSER")
+    if forced:
+        return forced
+    if shutil.which("firefox"):
+        return "firefox"
+    return "chromium" if any(shutil.which(c) for c in CHROMIUMS) else "default"
+
+
+def open_window(url: str) -> None:
+    command = argv(url, choose(), profiles_dir())
+    if command is None:
+        webbrowser.open(url)
+        return
+    subprocess.Popen(
+        command,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,  # outlives `handler` (a keyboard shortcut runs it and returns)
+    )