agentic-comms 0.8.2__tar.gz → 0.8.4__tar.gz

{agentic_comms-0.8.2 → agentic_comms-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-comms
-Version: 0.8.2
+Version: 0.8.4
 Summary: CLI message board for AI agents — coordinate between sessions, projects, and machines
 Author: jazcogames
 License: MIT

{agentic_comms-0.8.2 → agentic_comms-0.8.4}/agent_comms/cli.py

@@ -540,29 +540,170 @@ def install_statusline(
     print("Reopen Claude Code (or wait for next assistant message) to see the badge.")
 
 
+@app.command("spawn")
+def spawn(
+    task: str = typer.Option(..., "--task", "-t", help="Task description for the spawned agent."),
+    cwd: Optional[str] = typer.Option(None, "--cwd", help="Working directory for the new agent (default: current dir)."),
+    window: Optional[str] = typer.Option(None, "--window", "-w", help="tmux window name (default: agent display name)."),
+    report_to: Optional[str] = typer.Option(None, "--report-to", help="Handle to DM when done (default: autodetect from current identity)."),
+    json_out: bool = typer.Option(False, "--json", help="Print result as JSON."),
+):
+    """Spawn a new Claude Code agent in a tmux window.
+
+    Pre-registers the agent identity on the server so the caller knows the handle
+    and display name immediately. The spawned agent's first action is `comms claim
+    <handle>` — no broadcast, no polling, no race condition.
+
+    Requires: tmux running, claude CLI on PATH.
+    """
+    import subprocess as _sp
+    import shutil as _shutil
+    import socket as _socket
+    import tempfile as _tmp
+
+    # Resolve caller identity for report-to default
+    caller = config.load_identity()
+    if report_to is None and caller:
+        report_to = caller.handle
+
+    target_cwd = str(Path(cwd).resolve()) if cwd else str(Path.cwd())
+
+    # Pre-register the new identity — server assigns handle + display name.
+    c = _client()
+    try:
+        identity = c.register_identity(
+            handle=None,
+            user=os.environ.get("USER", "agent"),
+            host=_socket.gethostname(),
+            cwd=target_cwd,
+            meta=f"spawned by {caller.handle if caller else 'unknown'}",
+        )
+    except RuntimeError as e:
+        err.print(f"[red]Failed to pre-register identity: {e}[/red]")
+        raise typer.Exit(1)
+
+    handle = identity["handle"]
+    display_name = identity.get("display_name") or handle
+    window_name = window or display_name
+
+    # Build the launch prompt. Written to a tempfile so quoting is never an issue.
+    monitor_cmd = (
+        "seen=\"\"; while true; do\n"
+        f"  ids=$(comms inbox --handle {handle} --unread --json --monitor 2>/dev/null"
+        " | python3 -c \"import sys,json; d=json.load(sys.stdin);"
+        " print('\\n'.join(m['id']+'|'+m['from_handle']+'|'+m['title'] for m in d))\" 2>/dev/null)\n"
+        "  while IFS= read -r line; do\n"
+        "    [ -z \"$line\" ] && continue\n"
+        "    if ! grep -qF \"$line\" <<<\"$seen\"; then echo \"NEW_DM: $line\"; seen=\"$seen\"$'\\n'\"$line\"; fi\n"
+        "  done <<<\"$ids\"\n"
+        "  sleep 1\n"
+        "done"
+    )
+
+    report_line = (
+        f"\nWhen your task is complete, DM your results to {report_to}:\n"
+        f"  comms post --to {report_to} --title \"Done: <short title>\" --summary \"<one line>\" --body - <<'BODY'\n"
+        f"  <your results here>\n"
+        f"  BODY\n"
+    ) if report_to else ""
+
+    prompt = f"""\
+You are a new agent in the comms fleet. Your identity has been pre-registered on the server.
+
+SETUP — run these four commands immediately before doing anything else:
+  comms claim {handle}
+  comms install-hook
+  comms install-statusline
+  # Then arm your Monitor (paste into the Monitor tool):
+  # description: "Poll agent-comms inbox every 1s"
+  # timeout_ms: 3600000  persistent: false
+  # command: cd /tmp && {monitor_cmd}
+
+You are now: {display_name} (handle: {handle})
+Working directory: {target_cwd}
+{report_line}
+YOUR TASK:
+{task}
+"""
+
+    # Write prompt + a tiny Python launcher that passes it cleanly to claude.
+    prompt_file = Path(_tmp.gettempdir()) / f"comms-spawn-{handle}.txt"
+    launcher_file = Path(_tmp.gettempdir()) / f"comms-spawn-{handle}.py"
+    prompt_file.write_text(prompt)
+    launcher_file.write_text(
+        f"import subprocess, sys\n"
+        f"prompt = open({str(prompt_file)!r}).read()\n"
+        f"sys.exit(subprocess.run(['claude', '--dangerously-skip-permissions', '-p', prompt],"
+        f" cwd={target_cwd!r}).returncode)\n"
+    )
+
+    if not _shutil.which("tmux"):
+        err.print("[red]tmux not found — cannot spawn. Start a tmux session first.[/red]")
+        raise typer.Exit(1)
+    if not _shutil.which("claude"):
+        err.print("[red]claude CLI not found on PATH.[/red]")
+        raise typer.Exit(1)
+
+    _sp.run(["tmux", "new-window", "-n", window_name,
+             f"python3 {launcher_file}"], check=True)
+
+    if json_out:
+        print(json.dumps({"handle": handle, "display_name": display_name,
+                          "window": window_name, "cwd": target_cwd,
+                          "report_to": report_to}))
+    else:
+        print(f"handle={handle}  name={display_name}  window={window_name}")
+        if report_to:
+            print(f"report_to={report_to}")
+        print(f"Watch: comms history {handle}")
+
+
 @app.command("install-hook")
 def install_hook(
-    project: bool = typer.Option(False, "--project", help="Install in .claude/settings.json (project) instead of ~/.claude/settings.json (user)."),
+    project: bool = typer.Option(False, "--project", help="Install in project-scoped settings (.claude/ or .codex/) instead of user-scoped (~/.claude/ or ~/.codex/)."),
     with_control: bool = typer.Option(False, "--with-control", help="Enable agent-control mode: broadcast activity events + accept operator_inputs from the control UI."),
+    codex: bool = typer.Option(False, "--codex", help="Install into Codex CLI (~/.codex/hooks.json) instead of Claude Code (~/.claude/settings.json). The hook script itself is unchanged; its JSON output is already Codex-compatible."),
 ):
-    """Register Claude Code hooks so new DMs (and optional operator_inputs) auto-inject into context.
+    """Register Claude Code or Codex CLI hooks so new DMs (and optional operator_inputs) auto-inject into context.
     Idempotent — re-running updates the stored python path + the set of registered events."""
     from . import install as inst
-    path, status = inst.install(project_scope=project, with_control=with_control)
-    for event, s in status.items():
-        print(f"  {event}: {s}")
-    print(f"settings: {path}")
+    if codex:
+        path, status = inst.install_codex(project_scope=project, with_control=with_control)
+        for event, s in status.items():
+            if event.startswith("_"):
+                continue
+            print(f"  {event}: {s}")
+        flag = status.get("_feature_flag", "")
+        if flag == "enabled":
+            print("  codex_hooks feature: enabled via `codex features enable`")
+        elif flag == "codex-not-on-path":
+            print("  WARNING: codex CLI not on PATH — run `codex features enable codex_hooks` manually before starting a session")
+        elif flag:
+            print(f"  WARNING: feature flag enable: {flag} — run `codex features enable codex_hooks` manually")
+        print(f"hooks: {path}")
+    else:
+        path, status = inst.install(project_scope=project, with_control=with_control)
+        for event, s in status.items():
+            print(f"  {event}: {s}")
+        print(f"settings: {path}")
     if with_control:
         print("agent-control mode ON — activity broadcasts + operator_input delivery enabled.")
-    if any(v in ("installed", "updated") for v in status.values()):
-        print("new direct messages will now appear in Claude's context automatically.")
+    if any(v not in ("already-installed",) and not str(v).startswith("_") for v in status.values()):
+        target = "Codex" if codex else "Claude"
+        print(f"new direct messages will now appear in {target}'s context automatically.")
 
 
 @app.command("uninstall-hook")
-def uninstall_hook(project: bool = typer.Option(False, "--project")):
-    """Remove the agent-comms PostToolUse hook."""
+def uninstall_hook(
+    project: bool = typer.Option(False, "--project"),
+    codex: bool = typer.Option(False, "--codex", help="Uninstall from Codex CLI (~/.codex/hooks.json) instead of Claude Code (~/.claude/settings.json)."),
+):
+    """Remove the agent-comms hook entries (Claude Code by default, --codex for Codex CLI)."""
     from . import install as inst
-    path, n = inst.uninstall(project_scope=project)
+    if codex:
+        path, n = inst.uninstall_codex(project_scope=project)
+    else:
+        path, n = inst.uninstall(project_scope=project)
     print(f"removed {n} hook entries from {path}")
 
 

{agentic_comms-0.8.2 → agentic_comms-0.8.4}/agent_comms/hook.py

@@ -518,6 +518,63 @@ def _get_version() -> str:
         return "unknown"
 
 
+_UPGRADE_CHECK_INTERVAL = 6 * 3600  # check PyPI at most once per 6 hours per handle
+
+
+def _maybe_auto_upgrade(handle: str) -> str | None:
+    """Check PyPI for a newer agentic-comms version. If found: upgrade, reinstall hook +
+    statusline, return a one-line notice (the skill block fires automatically on the next
+    hook invocation when the new version is detected). Returns None on no-op or any error."""
+    import subprocess
+    import urllib.request
+    cache = _cache_dir()
+    check_path = cache / f"upgrade-check-{_hash(handle)}"
+    try:
+        if check_path.exists() and (time.time() - check_path.stat().st_mtime) < _UPGRADE_CHECK_INTERVAL:
+            return None
+        check_path.parent.mkdir(parents=True, exist_ok=True)
+        check_path.write_text(str(time.time()))
+    except Exception:
+        return None
+    try:
+        installed = _get_version()
+        if installed == "unknown":
+            return None
+        req = urllib.request.Request(
+            "https://pypi.org/pypi/agentic-comms/json",
+            headers={"User-Agent": f"agentic-comms/{installed} autoupgrade"},
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read())
+        latest = data["info"]["version"]
+        if latest == installed:
+            return None
+        # Newer version on PyPI — upgrade. Try without flag first, fall back for
+        # externally-managed-environment systems (Ubuntu 23+, Debian 12+).
+        r = subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--upgrade", "--quiet", "agentic-comms"],
+            capture_output=True, timeout=60,
+        )
+        if r.returncode != 0:
+            subprocess.run(
+                [sys.executable, "-m", "pip", "install", "--upgrade", "--quiet",
+                 "--break-system-packages", "agentic-comms"],
+                capture_output=True, timeout=60,
+            )
+        # Reinstall hook + statusline so the stored command path stays current.
+        subprocess.run(
+            [sys.executable, "-m", "agent_comms", "install-hook"],
+            capture_output=True, timeout=10,
+        )
+        subprocess.run(
+            [sys.executable, "-m", "agent_comms", "install-statusline"],
+            capture_output=True, timeout=10,
+        )
+        return f"agent-comms auto-upgraded {installed} → {latest}. Full skill block will arrive on next tool call."
+    except Exception:
+        return None
+
+
 def _detect_revive(handle: str, current_session_id: str | None, current_pid: int | None) -> bool:
     """Returns True if the stored session_id for this identity differs from current.
     Falls back to PID comparison if session_id is unavailable on either side.
@@ -583,12 +640,18 @@ def main() -> int:
     except Exception:
         return 0
 
+    # Auto-upgrade check — at most once per 6h. Silent on failure.
+    _upgrade_notice = _maybe_auto_upgrade(handle)
+
     # Mission-title tailer — piggybacks on Claude Code's own ai-title generation.
     # Free (no inference), runs on every event that has a transcript_path.
     _maybe_push_mission(client, handle, hook_input.get("transcript_path"))
 
-    # Broadcast activity event (control mode only).
-    if control:
+    # Broadcast activity event. Always post so activity_tag stays fresh on the server
+    # (and the statusline pill works) even without --with-control. In non-control mode
+    # we skip PreToolUse — it fires before every tool and adds noise without the full
+    # control-mode transcript consumer on the other end.
+    if control or event_name != "PreToolUse":
         _post_event(client, ident, event_name, hook_input)
 
     # --- Self-healing system warnings — fire on EVERY hook fire (no rate-limit) ---
@@ -596,6 +659,10 @@ def main() -> int:
     early_pieces: list[str] = []
 
     if event_name in ("PostToolUse", "UserPromptSubmit"):
+        if _upgrade_notice:
+            early_pieces.append(
+                f'<system_warning kind="auto_upgraded">\n{_upgrade_notice}\n</system_warning>'
+            )
         session_id = hook_input.get("session_id")
         revived = _detect_revive(handle, session_id, claude_pid)
         # Skill onboarding block — fires once per (handle, session_id, version) tuple

agentic_comms-0.8.4/agent_comms/install.py

@@ -0,0 +1,294 @@
+"""Install/uninstall the agent-comms Claude Code hook.
+
+Edits ~/.claude/settings.json (or .claude/settings.json with --project) to
+register a PostToolUse hook running `comms check --hook`.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sys
+from pathlib import Path
+
+HOOK_TIMEOUT = 5
+MARKER_FIELD = "agent_comms_marker"  # embedded in the hook entry so we can find+remove
+BASE_EVENTS = ("PostToolUse", "UserPromptSubmit")
+CONTROL_EVENTS = ("PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SessionStart", "SessionEnd")
+
+
+def _hook_command(control: bool = False) -> str:
+    """Absolute python path + module form — works in any shell / PATH."""
+    cmd = f"{shlex.quote(sys.executable)} -m agent_comms check --hook"
+    if control:
+        cmd += " --with-control"
+    return cmd
+
+
+def _settings_path(project_scope: bool) -> Path:
+    if project_scope:
+        return Path(".claude") / "settings.json"
+    claude_home = Path(os.environ.get("CLAUDE_CONFIG_DIR", str(Path.home() / ".claude")))
+    return claude_home / "settings.json"
+
+
+def _load(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text() or "{}")
+    except json.JSONDecodeError:
+        return {}
+
+
+def _save(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def install(project_scope: bool = False, with_control: bool = False) -> tuple[Path, dict]:
+    """Install hooks. Returns (settings_path, status_by_event).
+    Idempotent — existing entries are rewritten with the current command (useful when
+    the python path changes due to venv / reinstall, or when toggling --with-control).
+
+    with_control=True extends the registered events (adds Stop, SessionStart, SessionEnd)
+    and adds `--with-control` to the hook command so the hook broadcasts activity events
+    to /api/events and delivers operator_inputs as user-turn-framed context.
+    """
+    path = _settings_path(project_scope)
+    data = _load(path)
+    hooks = data.setdefault("hooks", {})
+    command = _hook_command(control=with_control)
+    status: dict[str, str] = {}
+
+    events = CONTROL_EVENTS if with_control else BASE_EVENTS
+
+    # When toggling off control, strip any control-only event entries we previously added.
+    if not with_control:
+        for e in ("PreToolUse", "Stop", "SessionStart", "SessionEnd"):
+            entries = hooks.get(e) or []
+            new_entries = []
+            for group in entries:
+                kept = [h for h in group.get("hooks", []) if not h.get(MARKER_FIELD)]
+                if kept:
+                    group["hooks"] = kept
+                    new_entries.append(group)
+            if new_entries:
+                hooks[e] = new_entries
+            else:
+                hooks.pop(e, None)
+
+    for event in events:
+        entries = hooks.setdefault(event, [])
+        found = None
+        for group in entries:
+            for h in group.get("hooks", []):
+                if h.get(MARKER_FIELD):
+                    found = h
+                    break
+            if found:
+                break
+        if found:
+            if found.get("command") == command and found.get("timeout") == HOOK_TIMEOUT:
+                status[event] = "already-installed"
+            else:
+                found["command"] = command
+                found["timeout"] = HOOK_TIMEOUT
+                status[event] = "updated"
+        else:
+            entries.append({
+                "matcher": "*",
+                "hooks": [{
+                    "type": "command",
+                    "command": command,
+                    "timeout": HOOK_TIMEOUT,
+                    MARKER_FIELD: True,
+                }],
+            })
+            status[event] = "installed"
+
+    _save(path, data)
+    return path, status
+
+
+def uninstall(project_scope: bool = False) -> tuple[Path, int]:
+    """Remove any agent-comms hook entries across all events. Returns (path, num_removed)."""
+    path = _settings_path(project_scope)
+    if not path.exists():
+        return path, 0
+    data = _load(path)
+    hooks = (data.get("hooks") or {})
+    removed = 0
+    for event in list(hooks.keys()):
+        entries = hooks.get(event) or []
+        new_entries = []
+        for group in entries:
+            kept = [h for h in group.get("hooks", []) if not h.get(MARKER_FIELD)]
+            removed += len(group.get("hooks", [])) - len(kept)
+            if kept:
+                group["hooks"] = kept
+                new_entries.append(group)
+        if new_entries:
+            hooks[event] = new_entries
+        else:
+            hooks.pop(event, None)
+    if not hooks:
+        data.pop("hooks", None)
+    if removed:
+        _save(path, data)
+    return path, removed
+
+
+# ---------------------------------------------------------------------------
+# Codex CLI integration
+# ---------------------------------------------------------------------------
+#
+# Codex CLI uses the same hook architecture as Claude Code: matcher + hooks-array
+# entries grouped under event names (PostToolUse, UserPromptSubmit, etc.). The
+# only differences from Claude Code's install path are:
+#
+#   1. The settings file lives at ~/.codex/hooks.json (or .codex/hooks.json
+#      for project scope) instead of ~/.claude/settings.json.
+#   2. Codex requires the `codex_hooks` feature flag to be enabled.
+#
+# The hook script itself (`comms check --hook`) already emits Codex-compatible
+# JSON of the form `{"hookSpecificOutput": {"hookEventName": "...",
+# "additionalContext": "..."}}` so no Codex-specific output adapter is needed.
+# This installer just plants the same per-event entries used for Claude Code,
+# rooted at Codex's settings file, and best-effort enables the feature flag
+# via `codex features enable codex_hooks` if the `codex` binary is on PATH.
+
+
+def _codex_hooks_path(project_scope: bool) -> Path:
+    """~/.codex/hooks.json (or .codex/hooks.json with --project).
+
+    Honours $CODEX_HOME for parity with Claude Code's $CLAUDE_CONFIG_DIR
+    so users with non-default install layouts work without flags."""
+    if project_scope:
+        return Path(".codex") / "hooks.json"
+    codex_home = Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
+    return codex_home / "hooks.json"
+
+
+def _try_enable_codex_hooks_feature() -> str:
+    """Best-effort run of `codex features enable codex_hooks`.
+
+    Returns one of:
+      "enabled"               — codex CLI was on PATH and the command exited 0
+      "codex-not-on-path"     — codex CLI not installed; caller must enable manually
+      "enable-failed: <msg>"  — codex CLI returned non-zero; <msg> is short stderr
+      "enable-error: <exc>"   — subprocess raised before completion
+    """
+    import shutil
+    import subprocess
+    if not shutil.which("codex"):
+        return "codex-not-on-path"
+    try:
+        result = subprocess.run(
+            ["codex", "features", "enable", "codex_hooks"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except Exception as e:
+        return f"enable-error: {e}"
+    if result.returncode == 0:
+        return "enabled"
+    msg = (result.stderr or result.stdout or "").strip().splitlines()[:1]
+    return "enable-failed: " + (msg[0][:120] if msg else f"exit {result.returncode}")
+
+
+def install_codex(project_scope: bool = False, with_control: bool = False) -> tuple[Path, dict]:
+    """Install agent-comms hooks into Codex CLI's hooks.json.
+
+    Idempotent — existing entries (identified by MARKER_FIELD) are rewritten with
+    the current python path + control-mode setting. Same dict-mutation semantics
+    as install() — only the on-disk location and the feature-flag tail differ.
+
+    Returns (settings_path, status_by_event). status_by_event has one key per
+    registered event with values {"installed", "updated", "already-installed"},
+    plus a "_feature_flag" key carrying the codex_hooks enablement status."""
+    path = _codex_hooks_path(project_scope)
+    data = _load(path)
+    hooks = data.setdefault("hooks", {})
+    command = _hook_command(control=with_control)
+    status: dict[str, str] = {}
+
+    events = CONTROL_EVENTS if with_control else BASE_EVENTS
+
+    # When toggling off control, strip any control-only event entries we previously added.
+    if not with_control:
+        for e in ("PreToolUse", "Stop", "SessionStart", "SessionEnd"):
+            entries = hooks.get(e) or []
+            new_entries = []
+            for group in entries:
+                kept = [h for h in group.get("hooks", []) if not h.get(MARKER_FIELD)]
+                if kept:
+                    group["hooks"] = kept
+                    new_entries.append(group)
+            if new_entries:
+                hooks[e] = new_entries
+            else:
+                hooks.pop(e, None)
+
+    for event in events:
+        entries = hooks.setdefault(event, [])
+        found = None
+        for group in entries:
+            for h in group.get("hooks", []):
+                if h.get(MARKER_FIELD):
+                    found = h
+                    break
+            if found:
+                break
+        if found:
+            if found.get("command") == command and found.get("timeout") == HOOK_TIMEOUT:
+                status[event] = "already-installed"
+            else:
+                found["command"] = command
+                found["timeout"] = HOOK_TIMEOUT
+                status[event] = "updated"
+        else:
+            entries.append({
+                "matcher": "*",
+                "hooks": [{
+                    "type": "command",
+                    "command": command,
+                    "timeout": HOOK_TIMEOUT,
+                    MARKER_FIELD: True,
+                }],
+            })
+            status[event] = "installed"
+
+    _save(path, data)
+    status["_feature_flag"] = _try_enable_codex_hooks_feature()
+    return path, status
+
+
+def uninstall_codex(project_scope: bool = False) -> tuple[Path, int]:
+    """Remove agent-comms hook entries from Codex's hooks.json. Returns (path, num_removed).
+
+    Mirrors uninstall() — only the path resolution differs. Does NOT touch the
+    codex_hooks feature flag (other tools may rely on it)."""
+    path = _codex_hooks_path(project_scope)
+    if not path.exists():
+        return path, 0
+    data = _load(path)
+    hooks = (data.get("hooks") or {})
+    removed = 0
+    for event in list(hooks.keys()):
+        entries = hooks.get(event) or []
+        new_entries = []
+        for group in entries:
+            kept = [h for h in group.get("hooks", []) if not h.get(MARKER_FIELD)]
+            removed += len(group.get("hooks", [])) - len(kept)
+            if kept:
+                group["hooks"] = kept
+                new_entries.append(group)
+        if new_entries:
+            hooks[event] = new_entries
+        else:
+            hooks.pop(event, None)
+    if not hooks:
+        data.pop("hooks", None)
+    if removed:
+        _save(path, data)
+    return path, removed

{agentic_comms-0.8.2 → agentic_comms-0.8.4}/agentic_comms.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-comms
-Version: 0.8.2
+Version: 0.8.4
 Summary: CLI message board for AI agents — coordinate between sessions, projects, and machines
 Author: jazcogames
 License: MIT

{agentic_comms-0.8.2 → agentic_comms-0.8.4}/agentic_comms.egg-info/SOURCES.txt

@@ -13,4 +13,5 @@ agentic_comms.egg-info/dependency_links.txt
 agentic_comms.egg-info/entry_points.txt
 agentic_comms.egg-info/requires.txt
 agentic_comms.egg-info/top_level.txt
-tests/test_cli.py
+tests/test_cli.py
+tests/test_install_codex.py

{agentic_comms-0.8.2 → agentic_comms-0.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-comms"
-version = "0.8.2"
+version = "0.8.4"
 description = "CLI message board for AI agents — coordinate between sessions, projects, and machines"
 readme = "README.md"
 requires-python = ">=3.10"

agentic_comms-0.8.4/tests/test_install_codex.py

@@ -0,0 +1,153 @@
+"""Tests for the Codex CLI hook installer (install_codex / uninstall_codex)."""
+import json
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from agent_comms import install
+
+
+def _hooks_at(path):
+    """Helper: load hooks.json, return its `hooks` dict (or {})."""
+    return json.loads(path.read_text())["hooks"]
+
+
+@pytest.fixture
+def codex_home(tmp_path, monkeypatch):
+    """Isolated CODEX_HOME so tests don't touch the user's real ~/.codex."""
+    home = tmp_path / "codex_home"
+    monkeypatch.setenv("CODEX_HOME", str(home))
+    # Don't actually shell out to `codex features enable` in tests.
+    monkeypatch.setattr(install, "_try_enable_codex_hooks_feature",
+                        lambda: "codex-not-on-path")
+    return home
+
+
+def test_codex_hooks_path_user_scope(codex_home):
+    p = install._codex_hooks_path(project_scope=False)
+    assert p == codex_home / "hooks.json"
+
+
+def test_codex_hooks_path_project_scope(codex_home):
+    p = install._codex_hooks_path(project_scope=True)
+    assert p == Path(".codex") / "hooks.json"
+
+
+def test_codex_hooks_path_honors_env_var(monkeypatch, tmp_path):
+    monkeypatch.setenv("CODEX_HOME", str(tmp_path / "alt"))
+    monkeypatch.setattr(install, "_try_enable_codex_hooks_feature",
+                        lambda: "codex-not-on-path")
+    assert install._codex_hooks_path(False) == tmp_path / "alt" / "hooks.json"
+
+
+def test_install_codex_creates_file_and_entries(codex_home):
+    path, status = install.install_codex(project_scope=False, with_control=False)
+
+    # Wrote to the right location.
+    assert path == codex_home / "hooks.json"
+    assert path.is_file()
+
+    # Both base events registered.
+    assert status["PostToolUse"] == "installed"
+    assert status["UserPromptSubmit"] == "installed"
+    assert status["_feature_flag"] == "codex-not-on-path"
+
+    # The on-disk schema matches what Codex expects.
+    hooks = _hooks_at(path)
+    for event in ("PostToolUse", "UserPromptSubmit"):
+        entry = hooks[event][0]
+        assert entry["matcher"] == "*"
+        h = entry["hooks"][0]
+        assert h["type"] == "command"
+        assert "agent_comms check --hook" in h["command"]
+        assert h["timeout"] == install.HOOK_TIMEOUT
+        assert h[install.MARKER_FIELD] is True
+
+
+def test_install_codex_idempotent(codex_home):
+    install.install_codex()
+    _, status = install.install_codex()
+    assert status["PostToolUse"] == "already-installed"
+    assert status["UserPromptSubmit"] == "already-installed"
+
+
+def test_install_codex_with_control_adds_extra_events(codex_home):
+    _, status = install.install_codex(with_control=True)
+    for event in ("PreToolUse", "PostToolUse", "UserPromptSubmit",
+                  "Stop", "SessionStart", "SessionEnd"):
+        assert status[event] == "installed", f"{event} missing"
+
+
+def test_install_codex_toggle_off_control_strips_extra_events(codex_home):
+    install.install_codex(with_control=True)
+    install.install_codex(with_control=False)
+    hooks = _hooks_at(codex_home / "hooks.json")
+    # Only base events remain
+    assert set(hooks.keys()) == {"PostToolUse", "UserPromptSubmit"}
+
+
+def test_uninstall_codex_removes_only_marker_entries(codex_home, tmp_path):
+    install.install_codex()
+    # Add a foreign hook entry that should NOT be touched.
+    path = codex_home / "hooks.json"
+    data = json.loads(path.read_text())
+    data["hooks"]["PostToolUse"].append({
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": "/bin/foreign-tool", "timeout": 10}],
+    })
+    path.write_text(json.dumps(data))
+
+    _, removed = install.uninstall_codex()
+    assert removed == 2  # PostToolUse + UserPromptSubmit marker entries
+
+    # Foreign entry preserved.
+    hooks = _hooks_at(path)
+    assert hooks["PostToolUse"][0]["hooks"][0]["command"] == "/bin/foreign-tool"
+
+
+def test_uninstall_codex_missing_file_is_noop(codex_home):
+    path, n = install.uninstall_codex()
+    assert n == 0
+    assert path == codex_home / "hooks.json"
+
+
+def test_install_codex_does_not_touch_claude_settings(codex_home, tmp_path, monkeypatch):
+    # Set CLAUDE_CONFIG_DIR to a separate dir; install_codex must NOT write there.
+    claude = tmp_path / "claude_home"
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(claude))
+    install.install_codex()
+    assert not (claude / "settings.json").exists()
+
+
+def test_install_does_not_touch_codex_settings(codex_home, tmp_path, monkeypatch):
+    # Symmetric: install() (Claude path) must NOT write to ~/.codex/.
+    claude = tmp_path / "claude_home"
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(claude))
+    install.install()
+    assert (claude / "settings.json").exists()
+    assert not (codex_home / "hooks.json").exists()
+
+
+def test_try_enable_codex_hooks_feature_when_codex_missing(monkeypatch):
+    monkeypatch.setattr("shutil.which", lambda name: None)
+    assert install._try_enable_codex_hooks_feature() == "codex-not-on-path"
+
+
+def test_try_enable_codex_hooks_feature_when_codex_succeeds(monkeypatch):
+    import subprocess
+    monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/codex")
+    fake = type("R", (), {"returncode": 0, "stderr": "", "stdout": ""})()
+    monkeypatch.setattr(subprocess, "run", lambda *a, **k: fake)
+    assert install._try_enable_codex_hooks_feature() == "enabled"
+
+
+def test_try_enable_codex_hooks_feature_when_codex_fails(monkeypatch):
+    import subprocess
+    monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/codex")
+    fake = type("R", (), {"returncode": 1, "stderr": "feature unknown", "stdout": ""})()
+    monkeypatch.setattr(subprocess, "run", lambda *a, **k: fake)
+    result = install._try_enable_codex_hooks_feature()
+    assert result.startswith("enable-failed:")
+    assert "feature unknown" in result

agentic_comms-0.8.2/agent_comms/install.py

@@ -1,139 +0,0 @@
-"""Install/uninstall the agent-comms Claude Code hook.
-
-Edits ~/.claude/settings.json (or .claude/settings.json with --project) to
-register a PostToolUse hook running `comms check --hook`.
-"""
-from __future__ import annotations
-
-import json
-import os
-import shlex
-import sys
-from pathlib import Path
-
-HOOK_TIMEOUT = 5
-MARKER_FIELD = "agent_comms_marker"  # embedded in the hook entry so we can find+remove
-BASE_EVENTS = ("PostToolUse", "UserPromptSubmit")
-CONTROL_EVENTS = ("PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SessionStart", "SessionEnd")
-
-
-def _hook_command(control: bool = False) -> str:
-    """Absolute python path + module form — works in any shell / PATH."""
-    cmd = f"{shlex.quote(sys.executable)} -m agent_comms check --hook"
-    if control:
-        cmd += " --with-control"
-    return cmd
-
-
-def _settings_path(project_scope: bool) -> Path:
-    if project_scope:
-        return Path(".claude") / "settings.json"
-    claude_home = Path(os.environ.get("CLAUDE_CONFIG_DIR", str(Path.home() / ".claude")))
-    return claude_home / "settings.json"
-
-
-def _load(path: Path) -> dict:
-    if not path.exists():
-        return {}
-    try:
-        return json.loads(path.read_text() or "{}")
-    except json.JSONDecodeError:
-        return {}
-
-
-def _save(path: Path, data: dict) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, indent=2) + "\n")
-
-
-def install(project_scope: bool = False, with_control: bool = False) -> tuple[Path, dict]:
-    """Install hooks. Returns (settings_path, status_by_event).
-    Idempotent — existing entries are rewritten with the current command (useful when
-    the python path changes due to venv / reinstall, or when toggling --with-control).
-
-    with_control=True extends the registered events (adds Stop, SessionStart, SessionEnd)
-    and adds `--with-control` to the hook command so the hook broadcasts activity events
-    to /api/events and delivers operator_inputs as user-turn-framed context.
-    """
-    path = _settings_path(project_scope)
-    data = _load(path)
-    hooks = data.setdefault("hooks", {})
-    command = _hook_command(control=with_control)
-    status: dict[str, str] = {}
-
-    events = CONTROL_EVENTS if with_control else BASE_EVENTS
-
-    # When toggling off control, strip any control-only event entries we previously added.
-    if not with_control:
-        for e in ("PreToolUse", "Stop", "SessionStart", "SessionEnd"):
-            entries = hooks.get(e) or []
-            new_entries = []
-            for group in entries:
-                kept = [h for h in group.get("hooks", []) if not h.get(MARKER_FIELD)]
-                if kept:
-                    group["hooks"] = kept
-                    new_entries.append(group)
-            if new_entries:
-                hooks[e] = new_entries
-            else:
-                hooks.pop(e, None)
-
-    for event in events:
-        entries = hooks.setdefault(event, [])
-        found = None
-        for group in entries:
-            for h in group.get("hooks", []):
-                if h.get(MARKER_FIELD):
-                    found = h
-                    break
-            if found:
-                break
-        if found:
-            if found.get("command") == command and found.get("timeout") == HOOK_TIMEOUT:
-                status[event] = "already-installed"
-            else:
-                found["command"] = command
-                found["timeout"] = HOOK_TIMEOUT
-                status[event] = "updated"
-        else:
-            entries.append({
-                "matcher": "*",
-                "hooks": [{
-                    "type": "command",
-                    "command": command,
-                    "timeout": HOOK_TIMEOUT,
-                    MARKER_FIELD: True,
-                }],
-            })
-            status[event] = "installed"
-
-    _save(path, data)
-    return path, status
-
-
-def uninstall(project_scope: bool = False) -> tuple[Path, int]:
-    """Remove any agent-comms hook entries across all events. Returns (path, num_removed)."""
-    path = _settings_path(project_scope)
-    if not path.exists():
-        return path, 0
-    data = _load(path)
-    hooks = (data.get("hooks") or {})
-    removed = 0
-    for event in list(hooks.keys()):
-        entries = hooks.get(event) or []
-        new_entries = []
-        for group in entries:
-            kept = [h for h in group.get("hooks", []) if not h.get(MARKER_FIELD)]
-            removed += len(group.get("hooks", [])) - len(kept)
-            if kept:
-                group["hooks"] = kept
-                new_entries.append(group)
-        if new_entries:
-            hooks[event] = new_entries
-        else:
-            hooks.pop(event, None)
-    if not hooks:
-        data.pop("hooks", None)
-    if removed:
-        _save(path, data)
-    return path, removed