handler-ai 0.1.0__py3-none-any.whl

handler_control/settings.py

@@ -0,0 +1,129 @@
+"""Daemon settings: where things live and how it listens. All overridable by environment.
+
+HANDLER_PORT                  listening port on 127.0.0.1 (default 7430)
+HANDLER_CONFIG_DIR            token file (default ~/.config/handler-ai)
+HANDLER_STATE_DIR             agents, sessions, apps (default ~/.local/state/handler-ai)
+HANDLER_DATA_DIR              the secret store, mini apps' versions, data
+                              (default ~/.local/share/handler-ai)
+HANDLER_ACCOUNTS_DIR          accounts (harness logins and keys) (default <config>/accounts)
+HANDLER_PROVIDERS_DIR         providers (endpoints, keys, models) (default <config>/providers)
+HANDLER_BINDINGS_DIR          bindings (addon + instance + credentials) (default <config>/bindings)
+HANDLER_AUTOMATIONS_DIR       automations (one folder each, I.1) (default <config>/automations)
+HANDLER_CACHE_DIR             the toolbox's global caches (default ~/.cache/handler-ai)
+HANDLER_RUNTIME_DIR           mini app backends' sockets
+                              (default $XDG_RUNTIME_DIR/handler-ai, else <state>)
+HANDLER_KNOWLEDGE_DIR         knowledge root: folders agents can be given; when unset, the root
+                              set from the web UI (<config>/knowledge.toml), else ~/knowledge
+HANDLER_ALLOWED_ORIGINS       extra browser origins, comma-separated (the daemon's own is allowed)
+HANDLER_TEMPLATES_DIR         starting points for providers (default: this package's
+                              data/templates)
+HANDLER_SESSION_IDLE_TIMEOUT  seconds before an unattached, idle session is stopped (default 1800)
+HANDLER_SESSION_MAX_ATTACH    clients attached to one session at once; beyond, the oldest is
+                              closed (default 8)
+HANDLER_APP_IDLE_TIMEOUT      seconds before an unused mini app's backend is stopped (default 600)
+HANDLER_TERMINAL              the terminal an account's login window opens in, a command line the
+                              command is appended to (default: the first found of
+                              terminal.TERMINALS)
+"""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from handler_contracts import DEFAULT_PORT, TOKEN_FILE_NAME
+
+HOST = "127.0.0.1"  # invariant 5: loopback only
+TEMPLATES = Path(__file__).resolve().parent / "data" / "templates"  # platform data, read-only
+# the built web UI (scripts/build-web-ui.sh writes it here; the wheel ships it)
+WEB_UI = Path(__file__).resolve().parent / "web-ui"
+
+
+@dataclass(frozen=True)
+class Sources:
+    """The folders an agent's account (accounts/<name>.toml) or provider
+    (providers/<name>.toml) is read from, and where accounts' login files are kept."""
+
+    accounts: Path
+    providers: Path
+    credentials: Path | None = None  # <data>/accounts; None: logins are not looked for
+
+
+@dataclass(frozen=True)
+class Settings:
+    port: int
+    config_dir: Path
+    state_dir: Path
+    bindings_dir: Path
+    allowed_origins: frozenset[str]
+    web_ui_dir: Path
+    session_idle_timeout: float = 1800.0
+    session_max_attach: int = 8
+    data_dir: Path = Path.home() / ".local" / "share" / "handler-ai"
+    app_idle_timeout: float = 600.0
+    knowledge_dir: Path | None = None  # forced by HANDLER_KNOWLEDGE_DIR; see knowledge.root
+    templates_dir: Path = TEMPLATES
+    accounts_dir: Path = Path.home() / ".config" / "handler-ai" / "accounts"
+    providers_dir: Path = Path.home() / ".config" / "handler-ai" / "providers"
+    skills_dir: Path = Path.home() / ".config" / "handler-ai" / "skills"  # skill library (D.17)
+    automations_dir: Path = Path.home() / ".config" / "handler-ai" / "automations"  # I.1
+    cache_dir: Path = Path.home() / ".cache" / "handler-ai"  # the toolbox's global caches
+    # sockets: short paths, tmpfs
+    runtime_dir: Path = Path.home() / ".local" / "state" / "handler-ai"
+
+    @property
+    def host(self) -> str:
+        return HOST
+
+    @property
+    def sources(self) -> Sources:
+        """Where an agent's account or provider is looked for."""
+        return Sources(self.accounts_dir, self.providers_dir, self.data_dir / "accounts")
+
+    @property
+    def token_file(self) -> Path:
+        return self.config_dir / TOKEN_FILE_NAME
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{HOST}:{self.port}"
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        home = Path.home()
+        xdg_config = Path(os.environ.get("XDG_CONFIG_HOME", home / ".config"))
+        xdg_state = Path(os.environ.get("XDG_STATE_HOME", home / ".local" / "state"))
+        xdg_data = Path(os.environ.get("XDG_DATA_HOME", home / ".local" / "share"))
+        xdg_cache = Path(os.environ.get("XDG_CACHE_HOME", home / ".cache"))
+        config_dir = Path(os.environ.get("HANDLER_CONFIG_DIR", xdg_config / "handler-ai"))
+        port = int(os.environ.get("HANDLER_PORT", DEFAULT_PORT))
+        state_dir = Path(os.environ.get("HANDLER_STATE_DIR", xdg_state / "handler-ai"))
+        xdg_runtime = os.environ.get("XDG_RUNTIME_DIR")
+        runtime_dir = Path(xdg_runtime) / "handler-ai" if xdg_runtime else state_dir
+        own = {f"http://{HOST}:{port}", f"http://localhost:{port}"}
+        extra = {
+            o.strip() for o in os.environ.get("HANDLER_ALLOWED_ORIGINS", "").split(",") if o.strip()
+        }
+        return cls(
+            port=port,
+            config_dir=config_dir,
+            state_dir=state_dir,
+            bindings_dir=Path(os.environ.get("HANDLER_BINDINGS_DIR", config_dir / "bindings")),
+            accounts_dir=Path(os.environ.get("HANDLER_ACCOUNTS_DIR", config_dir / "accounts")),
+            providers_dir=Path(os.environ.get("HANDLER_PROVIDERS_DIR", config_dir / "providers")),
+            skills_dir=Path(os.environ.get("HANDLER_SKILLS_DIR", config_dir / "skills")),
+            automations_dir=Path(
+                os.environ.get("HANDLER_AUTOMATIONS_DIR", config_dir / "automations")
+            ),
+            allowed_origins=frozenset(own | extra),
+            web_ui_dir=WEB_UI,
+            session_idle_timeout=float(os.environ.get("HANDLER_SESSION_IDLE_TIMEOUT", "1800")),
+            session_max_attach=max(1, int(os.environ.get("HANDLER_SESSION_MAX_ATTACH", "8"))),
+            data_dir=Path(os.environ.get("HANDLER_DATA_DIR", xdg_data / "handler-ai")),
+            cache_dir=Path(os.environ.get("HANDLER_CACHE_DIR", xdg_cache / "handler-ai")),
+            runtime_dir=Path(os.environ.get("HANDLER_RUNTIME_DIR", runtime_dir)),
+            app_idle_timeout=float(os.environ.get("HANDLER_APP_IDLE_TIMEOUT", "600")),
+            knowledge_dir=Path(forced)
+            if (forced := os.environ.get("HANDLER_KNOWLEDGE_DIR"))
+            else None,
+            templates_dir=Path(os.environ.get("HANDLER_TEMPLATES_DIR", TEMPLATES)),
+        )

handler_control/shortcuts.py

@@ -0,0 +1,80 @@
+"""GNOME keyboard shortcuts that open mini apps (H.7): one custom keybinding per app, at
+…/custom-keybindings/handler-<app>/, running `handler app open <app>`. Set through `gsettings`, as
+the daemon's user, in the desktop session it runs in; the person's own keybindings are left alone.
+"""
+
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SCHEMA = "org.gnome.settings-daemon.plugins.media-keys"
+BASE = "/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/"
+TIMEOUT = 10
+
+
+class ShortcutError(RuntimeError):
+    pass
+
+
+def entry_path(app: str) -> str:
+    return f"{BASE}handler-{app}/"
+
+
+def handler_command(app: str) -> str:
+    """What the shortcut runs: this install's `handler`, next to the daemon's interpreter."""
+    sibling = Path(sys.executable).parent / "handler"
+    return shlex.join([str(sibling) if sibling.exists() else "handler", "app", "open", app])
+
+
+def _gvariant_string(s: str) -> str:
+    return "'" + s.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def _gsettings(*args: str) -> str:
+    if not shutil.which("gsettings"):
+        raise ShortcutError("gsettings not found: keyboard shortcuts need GNOME")
+    try:
+        r = subprocess.run(
+            ["gsettings", *args], capture_output=True, text=True, timeout=TIMEOUT, check=False
+        )
+    except subprocess.TimeoutExpired:
+        raise ShortcutError("gsettings did not answer (no desktop session?)") from None
+    if r.returncode:
+        raise ShortcutError(r.stderr.strip() or f"gsettings exited {r.returncode}")
+    return r.stdout.strip()
+
+
+def _entries() -> list[str]:
+    out = _gsettings("get", SCHEMA, "custom-keybindings")
+    return [m.replace("\\'", "'") for m in re.findall(r"'((?:[^'\\]|\\.)*)'", out)]
+
+
+def _set_entries(paths: list[str]) -> None:
+    value = "[" + ", ".join(_gvariant_string(p) for p in paths) + "]" if paths else "@as []"
+    _gsettings("set", SCHEMA, "custom-keybindings", value)
+
+
+def install(app: str, binding: str) -> None:
+    """Bind `binding` (GNOME accelerator syntax, e.g. <Super>n) to opening `app`."""
+    path = entry_path(app)
+    relocatable = f"{SCHEMA}.custom-keybinding:{path}"
+    for key, value in (
+        ("name", f"handler: {app}"),
+        ("command", handler_command(app)),
+        ("binding", binding),
+    ):
+        _gsettings("set", relocatable, key, _gvariant_string(value))
+    entries = _entries()
+    if path not in entries:
+        _set_entries([*entries, path])
+
+
+def remove(app: str) -> None:
+    path = entry_path(app)
+    entries = _entries()
+    if path in entries:
+        _set_entries([p for p in entries if p != path])
+    _gsettings("reset-recursively", f"{SCHEMA}.custom-keybinding:{path}")

handler_control/skill_scan.py

@@ -0,0 +1,88 @@
+"""What handlerd finds in a skill's files, no model involved (D.17): what a model reading the skill
+cannot be talked out of. Shown on the skill's page and given to the agents reviewing it (D.18).
+
+    executables   files with the executable bit
+    binaries      files that are not UTF-8 text
+    hosts         URLs in its text, by host
+    hiddenText    invisible or bidirectional Unicode (format characters: zero-width, bidi
+                  controls, tags), which can hide instructions from a reader
+    blobs         long base64 or hex runs, which can hide a payload
+"""
+
+import re
+import unicodedata
+from pathlib import Path
+
+from handler_contracts import ScanHit, SkillScan
+
+from . import skills
+
+MAX_HITS = 100  # per kind
+URL = re.compile(r"\b[a-zA-Z][a-zA-Z0-9+.-]*://([^/\s\"'<>()\[\]`]+)")
+BLOB = re.compile(r"[A-Za-z0-9+/]{200,}={0,2}|\b[0-9a-fA-F]{128,}\b")
+BOM = "\ufeff"  # a byte order mark at the start of a file is not hidden text
+
+
+def scan(folder: Path) -> SkillScan:
+    """The scan of a skill's SKILL.md and other files (the ones agents get: no hidden files, no
+    symbolic links)."""
+    executables, binaries = [], []
+    hosts: list[ScanHit] = []
+    hidden: list[ScanHit] = []
+    blobs: list[ScanHit] = []
+    for f in [skills.SkillFile(skills.SKILL_FILE, 0, False), *skills.files_of(folder)]:
+        path = folder / f.path
+        if f.executable or skills.executable(path.stat().st_mode):
+            executables.append(f.path)
+        try:
+            text = path.read_bytes().decode()
+        except UnicodeDecodeError:
+            binaries.append(f.path)
+            continue
+        except OSError:
+            continue
+        for number, line in enumerate(text.splitlines(), 1):
+            for match in URL.finditer(line):
+                host = match.group(1).rsplit("@", 1)[-1].lower()
+                hosts.append(ScanHit(path=f.path, line=number, text=host))
+            if any(_hidden(c) for c in line.lstrip(BOM) if c not in "\t"):
+                hidden.append(ScanHit(path=f.path, line=number, text=_shown(line)))
+            if (blob := BLOB.search(line)) is not None:
+                blobs.append(ScanHit(path=f.path, line=number, text=blob.group()[:40] + "…"))
+    return SkillScan(
+        executables=executables[:MAX_HITS],
+        binaries=binaries[:MAX_HITS],
+        hosts=hosts[:MAX_HITS],
+        hidden_text=hidden[:MAX_HITS],
+        blobs=blobs[:MAX_HITS],
+    )
+
+
+def _hidden(c: str) -> bool:
+    return unicodedata.category(c) == "Cf"
+
+
+def _shown(line: str) -> str:
+    """The line with its hidden characters made visible (U+200B → ⟨U+200B⟩), shortened."""
+    shown = "".join(f"⟨U+{ord(c):04X}⟩" if _hidden(c) else c for c in line)
+    return shown if len(shown) <= 200 else shown[:199] + "…"
+
+
+def notes(found: SkillScan) -> str:
+    """The scan, for the agents reviewing the skill (D.18): what to look at first."""
+    lines = ["What handler found in its files, without a model (check these):"]
+    if found.executables:
+        lines.append(f"- executable files: {', '.join(found.executables)}")
+    if found.binaries:
+        lines.append(f"- binary files: {', '.join(found.binaries)}")
+    for name, hits in (
+        ("URLs (host)", found.hosts),
+        ("invisible or bidirectional characters", found.hidden_text),
+        ("long base64 or hex runs", found.blobs),
+    ):
+        if hits:
+            where = ", ".join(f"{h.path}:{h.line} {h.text}" for h in hits[:30])
+            lines.append(f"- {name}: {where}")
+    if len(lines) == 1:
+        lines.append("- nothing: no executable, binary, URL, hidden character or blob")
+    return "\n".join(lines)

handler_control/skill_sources.py

@@ -0,0 +1,61 @@
+"""Skills from a URL (D.17): a folder of a GitHub repository, or an https:// zip archive of one
+skill. handlerd downloads the archive (GitHub's zip of the repository at that ref) and takes the
+skill out of it with `skills.unpack`; the import itself is the archive import's.
+
+    locate   a URL → the archive to download and the folder in it (None: a skill's own archive)
+    fetch    a URL → the skill's name and files
+"""
+
+import posixpath
+import re
+
+import httpx
+
+from . import skills
+
+MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024  # a repository's archive; the skill in it: skills' limits
+DOWNLOAD_TIMEOUT = 60.0
+GITHUB = re.compile(
+    r"^https://github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+?)(?:\.git)?"
+    r"(?:/(?P<kind>tree|blob)/(?P<ref>[^/]+)(?:/(?P<path>.*?))?)?/?$"
+)
+
+
+def locate(url: str) -> tuple[str, str | None]:
+    """The archive to download, and the skill's folder in it: a GitHub repository's folder
+    (`tree/<ref>/<folder>`, a `blob/<ref>/<folder>/SKILL.md`, or the repository itself: its
+    default branch) is that folder of the repository's zip; any other https:// URL is a skill's
+    own archive (None). A branch whose name has a `/` is not told from a folder: the first
+    segment is taken as the ref."""
+    if not url.startswith("https://"):
+        raise skills.SkillError("a skill is fetched over https:// only")
+    found = GITHUB.match(url)
+    if not found:
+        return url, None
+    path = found["path"] or ""
+    if found["kind"] == "blob":
+        if posixpath.basename(path) != skills.SKILL_FILE:
+            raise skills.SkillError(f"a file link of a repository must be a {skills.SKILL_FILE}")
+        path = posixpath.dirname(path)
+    repository = f"https://github.com/{found['owner']}/{found['repo']}"
+    return f"{repository}/archive/{found['ref'] or 'HEAD'}.zip", path
+
+
+def _download(url: str) -> bytes:
+    data = bytearray()
+    try:
+        with httpx.stream("GET", url, follow_redirects=True, timeout=DOWNLOAD_TIMEOUT) as r:
+            r.raise_for_status()
+            for chunk in r.iter_bytes():
+                data += chunk
+                if len(data) > MAX_DOWNLOAD_BYTES:
+                    raise skills.SkillError(f"the archive is over {MAX_DOWNLOAD_BYTES} bytes")
+    except httpx.HTTPError as e:
+        raise skills.SkillError(f"cannot download {url}: {e}") from None
+    return bytes(data)
+
+
+def fetch(url: str) -> tuple[str, dict[str, tuple[bytes, bool]]]:
+    """The skill at `url`: its name and files, as `skills.unpack` gives them."""
+    archive, folder = locate(url)
+    return skills.unpack(_download(archive), folder)