@passioncode-ai/fabric-agent-adapter 0.39.0 → 0.40.0

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session_hosts.py

@@ -0,0 +1,265 @@
+"""working-with-fabric, part of fabric_session.py (FAA-65): install-host-hooks for Codex and Kimi Code, which writes
+only with --apply and refuses what it cannot read safely. Standard library only."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
+    CONFIG_CAP,
+    HOSTS,
+    NATIVE_PLUGIN_HOSTS,
+    _home,
+)
+
+
+try:  # Python 3.11+; only install-host-hooks --host kimi needs it, and refuses to write without it
+    import tomllib
+except ImportError:  # pragma: no cover — exercised by a test that removes it
+    tomllib = None  # type: ignore[assignment]
+
+
+class Refused(Exception):
+    pass
+
+
+def default_hook_script(env: Optional[Dict[str, str]] = None) -> Path:
+    """The skills install (stable across updates) when present, else this script's own path, symlinks kept."""
+    installed = _home(env) / ".agents" / "skills" / "working-with-fabric" / "scripts" / "fabric_session.py"
+    return installed if installed.is_file() else Path(__file__).absolute().with_name("fabric_session.py")  # the entry point
+
+
+def hook_command(script: str, host: str) -> str:
+    import shlex
+    quoted = '"%s"' % script if sys.platform == "win32" else shlex.quote(script)
+    return "python3 -S %s hook session-start --host %s" % (quoted, host)
+
+
+def _is_ours(command: Any, host: str) -> bool:
+    return isinstance(command, str) and "fabric_session.py" in command and \
+        command.rstrip().endswith("hook session-start --host %s" % host)
+
+
+def _digest(data: Optional[bytes]) -> str:
+    return hashlib.sha256(data).hexdigest() if data is not None else "absent"
+
+
+def _read_bytes(path: Path) -> Optional[bytes]:
+    try:
+        st = os.lstat(str(path))
+    except FileNotFoundError:
+        return None
+    import stat as _stat
+    if not _stat.S_ISREG(st.st_mode) or st.st_size > CONFIG_CAP:
+        raise Refused("%s is not a regular file of a reasonable size; nothing was changed" % path)
+    with open(str(path), "rb") as handle:
+        return handle.read()
+
+
+def _codex_doc(data: Optional[bytes]) -> Dict[str, Any]:
+    if data is None:
+        return {"hooks": {}}
+    try:
+        doc = json.loads(data.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        raise Refused("the file is not JSON, so its shape cannot be checked; nothing was changed")
+    shaped = isinstance(doc, dict) and isinstance(doc.get("hooks", {}), dict) and all(
+        isinstance(groups, list) and all(isinstance(g, dict) and isinstance(g.get("hooks", []), list)
+                                         and all(isinstance(h, dict) for h in g.get("hooks", [])) for g in groups)
+        for groups in doc.get("hooks", {}).values())
+    if not shaped:
+        raise Refused('the file has another shape than {"hooks": {"<Event>": [{"hooks": [...]}]}}; nothing was changed')
+    return doc
+
+
+def _codex_has(doc: Dict[str, Any], host: str) -> bool:
+    return any(_is_ours(h.get("command"), host) for g in doc.get("hooks", {}).get("SessionStart", [])
+               for h in g.get("hooks", []))
+
+
+def _kimi_hooks(data: Optional[bytes]) -> List[Any]:
+    if tomllib is None:
+        raise Refused("reading config.toml safely needs Python 3.11 (tomllib); nothing was changed; "
+                      "add the block above by hand, or run this with Python 3.11 or later")
+    try:
+        doc = tomllib.loads((data or b"").decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise Refused("the file is not valid TOML (%s); nothing was changed" % type(exc).__name__)
+    hooks = doc.get("hooks", [])
+    if not isinstance(hooks, list) or not all(isinstance(h, dict) for h in hooks):
+        raise Refused("`hooks` has another shape than an array of [[hooks]] tables; nothing was changed")
+    return hooks
+
+
+def _kimi_block(command: str) -> str:
+    return ("\n# fabric-agent-adapter (working-with-fabric): the Fabric session-start preamble. Remove it with\n"
+            "# fabric_session.py install-host-hooks --host kimi --remove\n"
+            "[[hooks]]\nevent = \"SessionStart\"\ncommand = %s\ntimeout = 5\n" % json.dumps(command))
+
+
+def _replace_file(path: Path, data: bytes, seen: Optional[bytes]) -> Optional[Path]:
+    """Back the file up, then write `data` atomically with the file's own mode. Refused when the file changed
+    since it was read. Returns the backup."""
+    if _read_bytes(path) != seen:
+        raise Refused("%s changed while this ran; nothing was changed" % path)
+    backup = None
+    mode = 0o600
+    if seen is not None:
+        mode = os.stat(str(path)).st_mode & 0o777
+        stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
+        for n in range(100):  # never overwrite an earlier backup, even one made the same second
+            backup = path.with_name("%s.%s%s.bak" % (path.name, stamp, "-%d" % n if n else ""))
+            if not os.path.lexists(str(backup)):
+                break
+        fd = os.open(str(backup), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(seen)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(".%s.%d.tmp" % (path.name, os.getpid()))
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "wb") as handle:
+        handle.write(data)
+    os.chmod(str(tmp), mode)
+    os.replace(str(tmp), str(path))
+    return backup
+
+
+def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] = None,
+                           out: Callable[[str], None] = print,
+                           err: Callable[[str], None] = lambda line: sys.stderr.write(line + "\n")) -> int:
+    import argparse
+    env = os.environ if env is None else env
+    parser = argparse.ArgumentParser(prog="fabric_session.py install-host-hooks",
+                                     description="Add (or remove) the Fabric session-start preamble hook in Codex or "
+                                                 "Kimi Code. A dry run unless --apply or --remove.")
+    parser.add_argument("--host", required=True)
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--dry-run", action="store_true", help="show the edit and write nothing (the default)")
+    mode.add_argument("--apply", action="store_true", help="make the edit, after backing the file up")
+    mode.add_argument("--remove", action="store_true", help="take this hook out again, after backing the file up")
+    parser.add_argument("--config", default=None, help="the file to edit (default: the host's own)")
+    parser.add_argument("--script", default=None, help="the fabric_session.py the hook runs")
+    parser.add_argument("--expect-sha256", default=None, help="refuse unless the file still has this digest")
+    try:
+        args = parser.parse_args(list(argv))
+    except SystemExit as exc:
+        return int(exc.code or 2)
+    if args.host in NATIVE_PLUGIN_HOSTS:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("_fabric_native_installer", Path(__file__).with_name("host_hooks.py"))
+        installer = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(installer)
+        return installer.main(list(argv), env=env, out=out, err=err)
+    if args.host not in ("codex", "kimi"):
+        err("install-host-hooks: --host must be codex, kimi, hermes, opencode, openclaw or pi (Claude uses its plugin)")
+        return 2
+    if args.config:
+        path = Path(args.config).expanduser()
+    elif args.host == "codex":
+        path = Path(env.get("CODEX_HOME") or str(_home(env) / ".codex")) / "hooks.json"
+    else:
+        path = _home(env) / ".kimi-code" / "config.toml"
+    command = hook_command(str(args.script or default_hook_script(env)), args.host)
+    shifted = 0  # Codex hook groups after ours, whose position a removal moves
+    try:
+        data = _read_bytes(path)
+        digest = _digest(data)
+        if args.expect_sha256 and args.expect_sha256 != digest:
+            raise Refused("%s changed since the dry run (sha256 now %s); nothing was changed" % (path, digest))
+        if args.host == "codex":
+            doc = _codex_doc(data)
+            present = _codex_has(doc, args.host)
+            entry = {"hooks": [{"type": "command", "command": command, "timeout": 5}]}
+            if args.remove:
+                if not present:
+                    out("install-host-hooks: no Fabric preamble hook in %s; nothing to change" % path)
+                    return 0
+                groups, dropped = [], None
+                for index, group in enumerate(doc["hooks"]["SessionStart"]):
+                    kept = [h for h in group.get("hooks", []) if not _is_ours(h.get("command"), args.host)]
+                    if kept or not group.get("hooks"):
+                        groups.append(dict(group, hooks=kept) if kept != group.get("hooks") else group)
+                    elif dropped is None:
+                        dropped = index  # a group that held only our hook goes; the groups after it move up
+                if dropped is not None:
+                    shifted = len(doc["hooks"]["SessionStart"]) - dropped - 1
+                if groups:
+                    doc["hooks"]["SessionStart"] = groups
+                else:
+                    del doc["hooks"]["SessionStart"]
+                new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
+            elif present:
+                owned = [h for g in doc["hooks"]["SessionStart"] for h in g.get("hooks", [])
+                         if _is_ours(h.get("command"), args.host)]
+                if len(owned) != 1:
+                    raise Refused("multiple Fabric hooks are configured; preserve their matchers and resolve duplicates before updating")
+                if owned[0]["command"] == command:
+                    out("install-host-hooks: the Fabric preamble hook is already in %s; nothing to change" % path)
+                    return 0
+                owned[0]["command"] = command
+                new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
+            else:
+                doc.setdefault("hooks", {}).setdefault("SessionStart", []).append(entry)
+                new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
+            change = "remove from hooks.SessionStart" if args.remove else "add to hooks.SessionStart"
+            shown = json.dumps(entry, indent=2)
+        else:
+            block = _kimi_block(command)
+            text = (data or b"").decode("utf-8", "replace")
+            if not (args.apply or args.remove):
+                present = tomllib is not None and any(_is_ours(h.get("command"), args.host) for h in _kimi_hooks(data))
+            else:
+                present = any(_is_ours(h.get("command"), args.host) for h in _kimi_hooks(data))
+            if args.remove:
+                if not present:
+                    out("install-host-hooks: no Fabric preamble hook in %s; nothing to change" % path)
+                    return 0
+                if block not in text:
+                    raise Refused("the Fabric hook in %s was edited by hand; remove its [[hooks]] table yourself" % path)
+                new_text = text.replace(block, "", 1)
+            elif present:
+                out("install-host-hooks: the Fabric preamble hook is already in %s; nothing to change" % path)
+                return 0
+            else:
+                new_text = text + ("" if not text or text.endswith("\n") else "\n") + block
+            new = new_text.encode("utf-8")
+            if args.apply or args.remove:
+                after = _kimi_hooks(new)
+                if len(after) != len(_kimi_hooks(data)) + (-1 if args.remove else 1):
+                    raise Refused("the edited file would not read back as expected; nothing was changed")
+            change = "remove from" if args.remove else "append to"
+            shown = block.strip("\n")
+        if not (args.apply or args.remove):
+            out("install-host-hooks: dry run, nothing is written.")
+            out("file: %s" % path)
+            out("sha256: %s" % digest)
+            out("would %s:" % change)
+            out(shown)
+            out("Apply it, on the person's go-ahead: fabric_session.py install-host-hooks --host %s --apply "
+                "--expect-sha256 %s" % (args.host, digest))
+            out("The hook only prints the preamble at session start (no turn observation, no unread count: %s "
+                "cannot rejoin its Fabric session yet). It is silent in a session Fabric launched.%s" % (
+                    HOSTS[args.host], " Codex may ask you to trust the new hook (/hooks) before it runs."
+                    if args.host == "codex" else ""))
+            return 0
+        backup = _replace_file(path, new, data)
+        out("install-host-hooks: %s %s %s." % ("removed the Fabric preamble hook from" if args.remove
+                                              else "added the Fabric preamble hook to", path,
+                                              "(backup: %s)" % backup if backup else "(new file)"))
+        out("Undo: fabric_session.py install-host-hooks --host %s %s" % (args.host, "--apply" if args.remove else "--remove"))
+        if shifted:
+            # Codex keys a hook's trust by its event, group and index: the groups after ours moved up one, so Codex asks
+            # the person to trust them again in /hooks before they run.
+            out("Codex trusts a hook by its position: %d SessionStart hook group(s) after the removed one moved, and "
+                "Codex will ask you to approve them again in /hooks." % shifted)
+        return 0
+    except Refused as exc:
+        err("install-host-hooks: refused: %s" % exc)
+        return 1
+    except OSError as exc:
+        err("install-host-hooks: %s could not be written (%s); nothing was changed" % (path, type(exc).__name__))
+        return 1

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session_mail.py

@@ -0,0 +1,155 @@
+"""working-with-fabric, part of fabric_session.py (FAA-65): watch-mail, one look at the board per interval while an
+agent waits on it, with backoff while Fabric is down. Standard library only."""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
+    BOARD_STATUS_TOOL,
+    HOOK_FEATURE,
+    SESSION_ID,
+    UNREAD_LINE,
+    VERSION,
+    WORKER_DEADLINE_S,
+    claude_registration,
+    fabric_launched,
+    fabric_root,
+    locate_hub,
+)
+from fabric_session_mcp import (  # noqa: E402 - the kit (FAA-65)
+    McpStdio,
+    _wait_for_session_tools,
+    board_unread,
+)
+
+
+WATCH_MIN_INTERVAL_S = 10
+
+
+WATCH_MAX_BACKOFF_S = 900
+
+
+def poll_unread(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None,
+                deadline_s: float = WORKER_DEADLINE_S) -> Tuple[str, Any]:
+    """One look at the board through `fabric-mcp --rejoin-only`: ("ok", count), ("unavailable", why) when Fabric
+    answers but the board cannot be read, ("down", why) when Fabric cannot be reached. No fabric-mcp starts unless
+    the running Fabric advertises session-hooks/1 (the rejoin)."""
+    env = dict(os.environ if env is None else env)
+    hub = locate_hub(fabric_root(env=env))
+    if hub["state"] != "running":
+        return "down", "Fabric is not running (%s)" % hub["reason"]
+    if HOOK_FEATURE not in hub.get("features", []):
+        return "down", "this Fabric does not advertise %s, so nothing can rejoin the session" % HOOK_FEATURE
+    registration = claude_registration(cwd, env)
+    if not registration:
+        return "down", "Claude Code has no MCP server named fabric"
+    client: Optional[McpStdio] = None
+    try:
+        deadline = time.monotonic() + deadline_s
+        argv = [registration["command"]] + registration["args"] + ["--rejoin-only", "--runtime-session-id", session_id]
+        client = McpStdio(argv, str(cwd), dict(env, CLAUDE_CODE_SESSION_ID=session_id), deadline)
+        client.request("initialize", {"protocolVersion": "2025-06-18", "capabilities": {},
+                                      "clientInfo": {"name": "fabric-agent-adapter-watch-mail", "version": VERSION}})
+        client.notify("notifications/initialized")
+        names = _wait_for_session_tools(client, deadline)
+        if BOARD_STATUS_TOOL not in names:
+            return "unavailable", "this Fabric serves no %s" % BOARD_STATUS_TOOL
+        unread, said = board_unread(client.request("tools/call", {"name": BOARD_STATUS_TOOL, "arguments": {}}))
+        return ("ok", unread) if unread is not None else ("unavailable", "the project board cannot be read (%s)" % said)
+    except TimeoutError:
+        return "down", "fabric-mcp did not join this session in time"
+    except Exception as exc:  # noqa: BLE001 — a poll never raises
+        return "down", "fabric-mcp failed (%s)" % type(exc).__name__
+    finally:
+        if client is not None:
+            client.close()
+
+
+def watch_mail(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None, interval: float = 60, *,
+               poll: Optional[Callable[[], Tuple[str, Any]]] = None, out: Callable[[str], None] = print,
+               wait: Callable[[float], bool], stop: Callable[[], bool], rng: Callable[[], float]) -> int:
+    """Poll the board every `interval` seconds (±20 % jitter, never under WATCH_MIN_INTERVAL_S) and print ONE line each
+    time the unread count rises. While Fabric is down or the board unreadable, say so once and back off, doubling up
+    to WATCH_MAX_BACKOFF_S. `wait(seconds)` returns True when it was told to stop."""
+    interval = max(float(WATCH_MIN_INTERVAL_S), float(interval))
+    poll = poll or (lambda: poll_unread(session_id, cwd, env))
+    last, trouble, backoff = 0, None, interval
+    while not stop():
+        kind, value = poll()
+        if kind == "ok":
+            if value > last:
+                out(UNREAD_LINE % value)
+            last, trouble, backoff = value, None, interval
+            delay = interval
+        else:
+            backoff = min(backoff * 2, float(WATCH_MAX_BACKOFF_S))
+            if trouble != kind:
+                out("watch-mail: %s; trying again, backing off up to %d minutes" % (value, WATCH_MAX_BACKOFF_S // 60))
+                trouble = kind
+            delay = backoff
+        if wait(delay * (0.8 + 0.4 * rng())):
+            break
+    return 0
+
+
+def watch_mail_cli(argv: Sequence[str], env: Optional[Dict[str, str]] = None) -> int:
+    import argparse
+    import random
+    import signal
+    import stat as _stat
+    import threading
+    env = os.environ if env is None else env
+    parser = argparse.ArgumentParser(prog="fabric_session.py watch-mail",
+                                     description="Print one line each time the project board's unread count rises.")
+    parser.add_argument("--interval", type=int, default=60, help="seconds between looks (at least %d)" % WATCH_MIN_INTERVAL_S)
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--session-id", default=None, help="the Claude Code session id (default: CLAUDE_CODE_SESSION_ID)")
+    args = parser.parse_args(list(argv))
+    session_id = args.session_id or env.get("CLAUDE_CODE_SESSION_ID") or ""
+    if not SESSION_ID.fullmatch(session_id):
+        sys.stderr.write("watch-mail needs the Claude Code session id: run it from Claude Code (it sets "
+                         "CLAUDE_CODE_SESSION_ID) or pass --session-id. Other agents cannot rejoin their session yet.\n")
+        return 2
+    if fabric_launched(env):
+        sys.stderr.write("watch-mail: this session was launched by Fabric; call com.status with your own tools.\n")
+        return 2
+    cwd = Path(args.cwd).expanduser()
+    if not claude_registration(cwd, env):
+        sys.stderr.write("watch-mail: Claude Code has no MCP server named fabric for %s; see working-with-fabric.\n" % cwd)
+        return 2
+    stopped = threading.Event()
+    for name in ("SIGTERM", "SIGINT", "SIGHUP"):
+        if hasattr(signal, name):
+            signal.signal(getattr(signal, name), lambda *_: stopped.set())
+    try:  # a pipe from the watcher that started us: its end is our end. /dev/null or a terminal is not.
+        mode = os.fstat(sys.stdin.fileno()).st_mode if sys.stdin else 0
+    except (OSError, ValueError):
+        mode = 0
+    if _stat.S_ISFIFO(mode) or _stat.S_ISSOCK(mode):
+        def drain() -> None:
+            try:
+                while sys.stdin.buffer.read1(4096) if hasattr(sys.stdin.buffer, "read1") else sys.stdin.read(4096):
+                    pass
+            except (OSError, ValueError):
+                pass
+            stopped.set()
+        threading.Thread(target=drain, daemon=True).start()
+    parent = os.getppid()
+
+    def wait(seconds: float) -> bool:
+        until = time.monotonic() + seconds
+        while not stopped.is_set():
+            left = until - time.monotonic()
+            if left <= 0:
+                return False
+            stopped.wait(min(left, 2.0))
+            if os.getppid() != parent:  # orphaned: whoever started us is gone
+                stopped.set()
+        return True
+
+    return watch_mail(session_id, cwd, env, args.interval, out=lambda line: print(line, flush=True),
+                      wait=wait, stop=stopped.is_set, rng=random.random)