@tiens.nguyen/gu-cli 1.0.739 → 1.0.741

package/gu_hooks.py

@@ -0,0 +1,231 @@
+"""Hooks for the gu agent (task #270): commands gu runs at fixed moments of a turn.
+
+    onStart     the first turn of a gu session (gu started, or /reset)
+    onAsk       every question, before the agent starts on it
+    onToolDone  after a tool the matcher names (gu's tool names: edit_file, grep_repo, mcp__…)
+    onTurnEnd   after the answer has been sent
+
+gu's own names and gu's own tool names, deliberately not Claude Code's. The worker hands the agent
+the hooks that apply (hooks-config.mjs: yours, plus a project's only once approved) and the
+session this turn belongs to.
+
+A HOOK IS A COMMAND. It gets one JSON object on stdin and may answer on stdout:
+    {"additionalContext": "..."}   added for the model (onStart, onAsk; onToolDone: after the result)
+    plain text                     the same as additionalContext
+    exit code 2                    stop: onAsk stops the turn, onToolDone tells the model; stderr is why
+A hook that fails any other way, or runs past its timeout, is a warning — never a failed turn.
+
+WHAT A HOOK SEES: its own env on a short whitelist of this process's (the worker's env carries gu's
+credentials), plus GU_PROJECT_DIR and GU_HOOK_EVENT. It runs in the project folder.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+from typing import Any, Callable
+
+EVENTS = ("onStart", "onAsk", "onToolDone", "onTurnEnd")
+DEFAULT_TIMEOUT_S = 30
+CONTEXT_CAP_CHARS = 6000
+_ENV_KEEP = ("PATH", "HOME", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TEMP", "TMP", "SHELL", "USER",
+             "USERNAME", "LOGNAME", "TERM", "SYSTEMROOT", "APPDATA", "LOCALAPPDATA", "USERPROFILE",
+             "PROGRAMDATA", "PATHEXT", "COMSPEC", "VIRTUAL_ENV", "PYTHONIOENCODING")
+_PLAIN_MATCHER = re.compile(r"^[A-Za-z0-9_\-| ,]*$")
+
+
+def matches(matcher: str | None, value: str) -> bool:
+    """Empty or "*" = everything. Letters, digits, _ - and | = an exact list. Anything else = a regex."""
+    m = (matcher or "").strip()
+    if m in ("", "*"):
+        return True
+    if _PLAIN_MATCHER.match(m):
+        return value in {x.strip() for x in re.split(r"[|,]", m) if x.strip()}
+    try:
+        return re.search(m, value) is not None
+    except re.error:
+        return False
+
+
+class HookResult:
+    def __init__(self):
+        self.context: list[str] = []
+        self.blocked: str | None = None
+        self.warnings: list[str] = []
+        self.ran = 0
+
+    @property
+    def text(self) -> str:
+        t = "\n\n".join(c for c in self.context if c.strip())
+        return t[:CONTEXT_CAP_CHARS] + ("\n… [hook output cut]" if len(t) > CONTEXT_CAP_CHARS else "")
+
+
+class HookRunner:
+    def __init__(self, hooks: dict, cwd: str | None, session_id: str,
+                 log: Callable[[str], None] = lambda s: None):
+        self.hooks = hooks if isinstance(hooks, dict) else {}
+        self.cwd = cwd if cwd and os.path.isdir(cwd) else None
+        self.session_id = session_id or "unknown"
+        self.log = log
+
+    def has(self, event: str) -> bool:
+        return bool(self.hooks.get(event))
+
+    def matcher_union(self, event: str) -> list[str]:
+        return [g.get("matcher", "") for g in self.hooks.get(event) or [] if isinstance(g, dict)]
+
+    def _env(self, event: str, extra: dict | None) -> dict:
+        env = {k: os.environ[k] for k in _ENV_KEEP if k in os.environ}
+        env.setdefault("PYTHONIOENCODING", "utf-8")
+        env["GU_PROJECT_DIR"] = self.cwd or ""
+        env["GU_HOOK_EVENT"] = event
+        for k, v in (extra or {}).items():
+            env[str(k)] = str(v)
+        return env
+
+    def run(self, event: str, payload: dict, match_value: str = "") -> HookResult:
+        res = HookResult()
+        if event not in EVENTS:
+            return res
+        body = {"event": event, "session_id": self.session_id, "cwd": self.cwd or "", **payload}
+        data = json.dumps(body, ensure_ascii=False, default=str)
+        for group in self.hooks.get(event) or []:
+            if not isinstance(group, dict) or not matches(group.get("matcher"), match_value):
+                continue
+            for h in group.get("hooks") or []:
+                if not isinstance(h, dict) or (h.get("type") or "command") != "command" or not h.get("command"):
+                    continue
+                self._one(event, h, data, res)
+        return res
+
+    def _one(self, event: str, h: dict, data: str, res: HookResult) -> None:
+        cmd = str(h["command"])
+        args = [str(a) for a in (h.get("args") or [])]
+        timeout = float(h.get("timeout") or DEFAULT_TIMEOUT_S)
+        label = os.path.basename(args[-1] if args else cmd.split()[0])
+        t0 = time.time()
+        res.ran += 1
+        try:
+            p = subprocess.run([cmd, *args] if args else cmd, shell=not args, input=data,
+                               capture_output=True, text=True, encoding="utf-8", errors="replace",
+                               timeout=timeout, cwd=self.cwd, env=self._env(event, h.get("env")))
+        except subprocess.TimeoutExpired:
+            res.warnings.append(f"{event} hook {label} took longer than {timeout:.0f}s and was stopped")
+            self.log(f"hook {event} {label}: timeout {timeout:.0f}s")
+            return
+        except OSError as e:
+            res.warnings.append(f"{event} hook {label} could not start: {e.strerror or e}")
+            self.log(f"hook {event} {label}: could not start")
+            return
+        ms = int((time.time() - t0) * 1000)
+        out = (p.stdout or "").strip()
+        err = (p.stderr or "").strip()
+        # Sizes only: a hook's output is conversation content, and the log is content-free (#249).
+        self.log(f"hook {event} {label}: exit {p.returncode} in {ms}ms, {len(out)} chars out")
+        if p.returncode == 2:
+            res.blocked = err or f"the {event} hook {label} said no"
+            return
+        if p.returncode != 0:
+            tail = err.splitlines()[-1][:200] if err else ""
+            res.warnings.append(f"{event} hook {label} failed (exit {p.returncode})" + (f": {tail}" if tail else ""))
+            return
+        if not out:
+            return
+        try:
+            obj = json.loads(out)
+        except ValueError:
+            res.context.append(out)  # plain text = context
+            return
+        if isinstance(obj, dict):
+            if str(obj.get("decision", "")).lower() == "block":
+                res.blocked = str(obj.get("reason") or err or f"the {event} hook {label} said no")
+                return
+            ctx = obj.get("additionalContext")
+            if isinstance(ctx, str) and ctx.strip():
+                res.context.append(ctx)
+
+
+# ---- onStart: once per session ---------------------------------------------------------------
+
+def _state_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".gonext", "hooks-state.json")
+
+
+def is_new_session(cwd: str, session_id: str, path: str | None = None) -> bool:
+    """True the first time this session is seen for this folder — and records it."""
+    path = path or _state_path()
+    key = os.path.realpath(cwd or "")
+    try:
+        with open(path, encoding="utf-8") as fh:
+            state = json.load(fh)
+        if not isinstance(state, dict):
+            state = {}
+    except (OSError, ValueError):
+        state = {}
+    if state.get(key) == session_id:
+        return False
+    state[key] = session_id
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = f"{path}.{os.getpid()}.tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(state, fh, indent=2)
+        os.replace(tmp, path)
+    except OSError:
+        pass
+    return True
+
+
+# ---- onToolDone: wrapping the agent's tools ---------------------------------------------------
+
+def wrap_tools(tools: list, runner: HookRunner, clip: int = 4000) -> int:
+    """Run onToolDone after every tool a matcher names. Returns how many tools were wrapped. Hook
+    context is appended to the tool's result; a block (exit 2) is appended as a message."""
+    if not runner.has("onToolDone"):
+        return 0
+    matchers = runner.matcher_union("onToolDone")
+    n = 0
+    for t in tools:
+        name = getattr(t, "name", "")
+        if not name or name == "final_answer" or not any(matches(m, name) for m in matchers):
+            continue
+        orig = t.forward
+        order = list((getattr(t, "inputs", None) or {}).keys())
+
+        def forward(*pos, _orig=orig, _name=name, _order=order, **kw):
+            result = _orig(*pos, **kw)
+            args = dict(kw)
+            for k, v in zip(_order, pos):
+                args.setdefault(k, v)
+            text = str(result)
+            r = runner.run("onToolDone", {"tool_name": _name, "tool_input": args,
+                                          "tool_result": text[:clip]}, match_value=_name)
+            extra = []
+            if r.blocked:
+                extra.append(f"[onToolDone hook] {r.blocked}")
+            if r.text:
+                extra.append(f"[onToolDone hook]\n{r.text}")
+            return f"{result}\n\n" + "\n".join(extra) if extra and isinstance(result, str) else result
+
+        t.forward = forward
+        n += 1
+    return n
+
+
+def from_cfg(cfg: dict, log: Callable[[str], None]) -> HookRunner | None:
+    hooks = cfg.get("hooks")
+    if not isinstance(hooks, dict) or not any(hooks.get(e) for e in EVENTS):
+        return None
+    sess = cfg.get("hookSession") if isinstance(cfg.get("hookSession"), dict) else {}
+    cwd = (cfg.get("activeWorkspace") or "").strip() or None
+    if sess.get("id"):
+        return HookRunner(hooks, cwd, str(sess["id"]), log)
+    # No terminal session (the web, or a terminal older than hooks). The job id would be a NEW
+    # "session" every turn — onStart on every question — so onStart is skipped, and the other
+    # events share one id per day, which keeps the memory hook's steps together.
+    import datetime
+    runner = HookRunner(hooks, cwd, "gu-" + datetime.date.today().isoformat(), log)
+    runner.hooks = {k: v for k, v in runner.hooks.items() if k != "onStart"}
+    return runner