agent-toggle 0.1.0__py3-none-any.whl

agent_toggle/__init__.py

@@ -0,0 +1,3 @@
+"""agent-toggle: temporarily disable / re-enable AI-agent resources."""
+
+__version__ = "0.1.0"

agent_toggle/__main__.py

@@ -0,0 +1,3 @@
+from agent_toggle.cli import main
+
+raise SystemExit(main())

agent_toggle/backends/flag_json.py

@@ -0,0 +1,141 @@
+"""Boolean flag in a JSON config (DESIGN s4, s5.5): openclaw skills/plugins, opencode mcp.
+
+The edit is TEXT-LEVEL: walk to the value span and replace only the `true` /
+`false` token, so comments-free formatting, key order, escapes, CRLF, tabs and
+a BOM all survive byte for byte. Never json.dump the whole file.
+
+Decisions:
+- Strict JSON only. opencode.json may be JSONC (comments, trailing commas) and
+  the openclaw config may be JSON5; such files are REFUSED (FlagError), never
+  silently rewritten, since a re-serialise would drop the user's comments.
+- A missing pointer is refused: we never invent a key, because an absent key
+  means the harness default, which we cannot know.
+- A duplicated key anywhere in the file is refused: which copy the harness
+  honours is parser-specific, so flipping either one could be a no-op.
+- The shapes `skills.entries.<name>.enabled`, `plugins.entries.<name>.enabled`
+  (openclaw) and `mcp.<name>.enabled` (opencode) are ASSUMED from DESIGN s4/s11,
+  not verified on a real install.
+"""
+from __future__ import annotations
+
+import json
+from json.decoder import WHITESPACE, scanstring
+from pathlib import Path
+from typing import Sequence
+
+from agent_toggle import fs
+
+_DECODER = json.JSONDecoder()
+BOM = "\ufeff"
+
+
+class FlagError(ValueError):
+    """The flag cannot be read or set safely; the message says why."""
+
+
+class FlagMissing(FlagError):
+    """The file or the pointer does not exist (as opposed to an unsafe file)."""
+
+
+def _no_dupes(pairs):
+    seen = set()
+    for k, _ in pairs:
+        if k in seen:
+            raise FlagError(f"duplicate key {k!r}")
+        seen.add(k)
+    return dict(pairs)
+
+
+def _no_constant(name):
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def _strict(text: str, where: str) -> None:
+    """Parse as strict JSON (no comments, trailing commas, NaN, duplicate keys)."""
+    try:
+        json.loads(text.removeprefix(BOM), object_pairs_hook=_no_dupes,
+                   parse_constant=_no_constant)
+    except FlagError as e:
+        raise FlagError(f"{where}: {e}; refusing to edit") from None
+    except (ValueError, RecursionError) as e:     # 3.10-3.12 recurse on deep nesting
+        raise FlagError(f"{where}: not strict JSON (JSONC/JSON5 is not supported): {e}") \
+            from None
+
+
+def _ws(text: str, i: int) -> int:
+    return WHITESPACE.match(text, i).end()
+
+
+def _span(text: str, pointer: Sequence[str], where: str) -> tuple[int, int, bool]:
+    """(start, end, value) of the boolean token at `pointer`. `text` must already
+    have passed _strict, so the walk only has to find, not validate."""
+    shown = ".".join(pointer)
+    if not pointer:
+        raise FlagError(f"{where}: empty pointer")
+    i = _ws(text, 1 if text.startswith(BOM) else 0)
+    for depth, want in enumerate(pointer):
+        if text[i:i + 1] != "{":
+            raise FlagMissing(f"{where}: {shown} not found")
+        i = _ws(text, i + 1)
+        while True:
+            if text[i] == "}":
+                raise FlagMissing(f"{where}: {shown} not found")
+            key, i = scanstring(text, i + 1)         # text[i] is the opening quote
+            i = _ws(text, _ws(text, i) + 1)          # past ':'
+            if key == want:
+                break
+            _, i = _DECODER.raw_decode(text, i)      # skip this value
+            i = _ws(text, i)
+            if text[i] == ",":
+                i = _ws(text, i + 1)
+    for token, value in (("true", True), ("false", False)):
+        if text.startswith(token, i):
+            return i, i + len(token), value
+    raise FlagError(f"{where}: {shown} is not a boolean")
+
+
+def _load(file: Path) -> str:
+    try:
+        text = Path(file).read_bytes().decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise FlagError(f"{file}: not strict JSON (not UTF-8: {e})") from None
+    except OSError as e:                         # missing / unreadable: a row, not a traceback
+        raise (FlagMissing if isinstance(e, FileNotFoundError) else FlagError)(f"{file}: cannot read ({e.strerror or e})") from None
+    _strict(text, str(file))
+    return text
+
+
+def read_flag(file: Path, pointer: Sequence[str]) -> bool:
+    """The boolean at `pointer` (a sequence of object keys) in `file`."""
+    text = _load(file)
+    return _span(text, pointer, str(file))[2]
+
+
+def set_flag(file: Path, pointer: Sequence[str], value: bool) -> bool:
+    """Set the boolean at `pointer` to `value`; return the previous value.
+
+    Same value -> no write. Otherwise written through fs.checked_write; the
+    invariant is that the file reads back as exactly `before` with only that
+    token swapped, still strict JSON, with the new value at `pointer`. Any
+    mismatch (including a concurrent edit since our read) rolls back and
+    raises fs.WriteError.
+    """
+    where = str(file)
+    text = _load(file)
+    start, end, was = _span(text, pointer, where)
+    if was is bool(value):
+        return was
+    expected = text[:start] + ("true" if value else "false") + text[end:]
+
+    def verify(before: str, after: str) -> str:
+        if before != text:
+            raise ValueError("file changed since it was read")
+        if after != expected:
+            raise ValueError("result differs from the one-token edit")
+        _strict(after, where)
+        if _span(after, pointer, where)[2] is not bool(value):
+            raise ValueError("flag did not take the new value")
+        return ""
+
+    fs.checked_write(Path(file), expected, verify)
+    return was

agent_toggle/backends/mcp_json.py

@@ -0,0 +1,198 @@
+"""JSON-key MCP backend: raw server entries in ~/.claude.json."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .. import fs
+
+
+def claude_mcp_config(name: str) -> tuple[dict, str, str | None] | None:
+    """Find a server's RAW config in ~/.claude.json -> (config, scope, project).
+
+    `claude mcp get` prints a human summary that silently drops auth fields
+    (headers, headersHelper), so a backup built from it restores a server that
+    then fails with 401. The raw entry is the only lossless source.
+
+    Two places hold one: user scope at the top level, and local scope nested
+    under projects/<dir>. The project path travels with the backup because
+    `claude mcp remove -s local` only sees the project it is run in -- restore
+    it from the wrong directory and the server reappears in the wrong project.
+
+    Raises LookupError when one name is local-scope in several projects and
+    the cwd does not pick a winner.
+    """
+    try:
+        cfg = json.loads(fs.claude_json().read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    raw = cfg.get("mcpServers", {}).get(name)
+    if raw is not None:
+        return raw, "user", None
+
+    hits = [(proj, pdata["mcpServers"][name])
+            for proj, pdata in cfg.get("projects", {}).items()
+            if isinstance(pdata, dict) and name in (pdata.get("mcpServers") or {})]
+    if not hits:
+        return None
+    cwd = str(Path.cwd())
+    for proj, raw in hits:
+        if proj == cwd:
+            return raw, "local", proj
+    if len(hits) > 1:
+        raise LookupError(
+            f"local-scope in {len(hits)} projects "
+            f"({', '.join(p for p, _ in hits)}) -- cd into the one you mean")
+    return hits[0][1], "local", hits[0][0]
+
+
+def claudeai_connector_names() -> set[str]:
+    """Names claude.ai connectors are known under (account-level, no local
+    mcpServers entry -- .claudeAiMcpEverConnected is the only place they are
+    listed)."""
+    try:
+        cfg = json.loads(fs.claude_json().read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return set()
+    return set(cfg.get("claudeAiMcpEverConnected", []) or [])
+
+
+def toggle_claudeai_connector(action: str, name: str,
+                              dry_run: bool = False) -> tuple[bool, list | str]:
+    """Fan a claude.ai connector on/off across every EXISTING project entry
+    in ~/.claude.json's disabledMcpServers list -- the only place /mcp writes
+    that state; no `claude mcp` CLI verb reaches it.
+
+    ponytail: covers projects that exist now; a project dir opened for the
+    first time later starts without the entry until this is re-run for it.
+    """
+    path = fs.claude_json()
+    try:
+        cfg = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        return False, f"~/.claude.json unreadable: {e}"
+
+    touched = []
+    for proj, pdata in cfg.get("projects", {}).items():
+        if not isinstance(pdata, dict):
+            continue
+        cur = pdata.get("disabledMcpServers") or []
+        has = name in cur
+        if action == "disable" and not has:
+            pdata["disabledMcpServers"] = [*cur, name]
+            touched.append(proj)
+        elif action == "enable" and has:
+            pdata["disabledMcpServers"] = [n for n in cur if n != name]
+            touched.append(proj)
+
+    if not touched or dry_run:
+        return True, touched
+    text = json.dumps(cfg, indent=2, ensure_ascii=False)
+    try:
+        fs.checked_write(path, text, fs.json_verify(text))
+    except fs.WriteError as e:                # rolled back to the previous bytes
+        return False, str(e)
+    return True, touched
+
+
+# ---------------------------------------------------- project <dir>/.mcp.json
+# The file is repo-controlled text: strict JSON only (no JSONC/BOM/duplicate keys),
+# never edited through a symlink, never larger than MAX_PROJECT_MCP.
+
+MAX_PROJECT_MCP = 4 << 20
+
+
+class ProjectMcpError(Exception):
+    """A .mcp.json that must not be edited; the message is the error row detail."""
+
+
+def _no_dup(pairs: list) -> dict:
+    out: dict = {}
+    for k, v in pairs:
+        if k in out:
+            raise ValueError(f"duplicate key {k!r}")
+        out[k] = v
+    return out
+
+
+def _not_json(const: str):
+    raise ValueError(f"{const} is not JSON")
+
+
+def _finite(num: str) -> float:
+    f = float(num)
+    if f in (float("inf"), float("-inf")):
+        raise ValueError(f"{num} is out of range")
+    return f
+
+
+def read_project_mcp(file: Path) -> tuple[str, dict]:
+    """(exact text, parsed object) of a project .mcp.json, or ProjectMcpError."""
+    if file.is_symlink():
+        raise ProjectMcpError(f"{file} is a symlink -- refusing to edit through it")
+    try:
+        if file.stat().st_size > MAX_PROJECT_MCP:
+            raise ProjectMcpError(f"{file} is larger than {MAX_PROJECT_MCP >> 20} MiB")
+        text = file.read_bytes().decode("utf-8")      # bytes: CRLF must survive
+    except FileNotFoundError:
+        raise ProjectMcpError(f"{file} not found") from None
+    except (OSError, UnicodeDecodeError) as e:
+        raise ProjectMcpError(f"{file} unreadable: {e}") from None
+    try:
+        obj = json.loads(text, object_pairs_hook=_no_dup, parse_constant=_not_json,
+                         parse_float=_finite)
+        json.dumps(obj, ensure_ascii=False).encode("utf-8")    # lone surrogates
+    except (ValueError, RecursionError) as e:
+        raise ProjectMcpError(f"{file} is not strict JSON ({e}) -- refusing "
+                              f"(JSONC, BOM, trailing commas and duplicate keys are not supported)"
+                              ) from None
+    if not isinstance(obj, dict) or not isinstance(obj.get("mcpServers"), dict):
+        raise ProjectMcpError(f"{file} has no mcpServers object")
+    return text, obj
+
+
+def _dump_like(obj: dict, text: str) -> str:
+    """Serialise `obj` in the layout of `text` (tab/2-space indent, CRLF, final newline)."""
+    out = json.dumps(obj, indent="\t" if "\n\t" in text else 2 if "\n" in text else None,
+                     ensure_ascii=False)
+    if text.endswith("\n"):
+        out += "\n"
+    return out.replace("\n", "\r\n") if "\r\n" in text else out
+
+
+def project_mcp_remove(file: Path, name: str) -> tuple[dict, str, str]:
+    """Plan the removal of `name`: (its raw entry, text before, text after). Writes nothing."""
+    text, obj = read_project_mcp(file)
+    if name not in obj["mcpServers"]:
+        raise ProjectMcpError(f"no mcpServers.{name} in {file}")
+    raw = obj["mcpServers"].pop(name)
+    return raw, text, _dump_like(obj, text)
+
+
+def project_mcp_restore(file: Path, name: str, payload: dict) -> tuple[str, str]:
+    """Plan putting `name` back: (current text, new text). The new text is the exact
+    pre-disable text when the file is still as we left it, else the entry merged into
+    the current file. Writes nothing."""
+    text, obj = read_project_mcp(file)
+    if name in obj["mcpServers"]:
+        raise ProjectMcpError(f"mcpServers.{name} is already defined in {file} -- "
+                              f"remove it first, the backup stays in state")
+    if text == payload["after"]:
+        return text, payload["before"]
+    obj["mcpServers"][name] = payload["entry"]
+    return text, _dump_like(obj, text)
+
+
+def write_project_mcp(file: Path, text: str, expect_before: str) -> None:
+    """Replace the file with `text` (the whole planned result); fs.WriteError, with
+    the previous bytes and mode restored, when the file is no longer `expect_before`
+    (an editor saved between plan and write) or the written result is not exactly `text`."""
+    check = fs.json_verify(text)
+
+    def verify(before: str, after: str) -> str:
+        if before != expect_before:
+            raise ValueError("the file changed while it was being edited")
+        return check(before, after)
+
+    fs.checked_write(file, text, verify)

agent_toggle/backends/mcp_toml.py

@@ -0,0 +1,90 @@
+"""TOML-block MCP backend (codex config.toml): verbatim text slices."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .. import fs
+
+
+def toml_block(text: str, name: str) -> tuple[int, int] | None:
+    """Line span of `[mcp_servers.<name>]` and its sub-tables, or None.
+
+    Returned as a slice so the backup is the VERBATIM source text. Python's
+    stdlib reads TOML (tomllib) but cannot write it, and hand-rolling a
+    serializer would mangle comments and formatting -- a text slice is both
+    lossless and far less code.
+    """
+    lines = text.splitlines(keepends=True)
+    head = f"[mcp_servers.{name}]"
+    sub = f"[mcp_servers.{name}."
+    start = end = None
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s == head:
+            start = i
+            end = len(lines)
+        elif start is not None and s.startswith("["):
+            if not s.startswith(sub):
+                end = i
+                break
+    return None if start is None else (start, end)
+
+
+def remove_verify(text: str, name: str, block: str):
+    """verify() for a removal planned against `text`: the file is still exactly what we
+    read (no concurrent edit), and only that block is gone. The note says
+    `unverified (no tomllib)` when no TOML parser could also parse the result."""
+    parse = fs.toml_verify()
+
+    def verify(before: str, after: str) -> str:
+        if before != text:
+            raise ValueError("file changed since it was read")
+        if after != before.replace(block, "", 1) or toml_block(after, name) is not None:
+            raise ValueError("result differs from the one-block removal")
+        return parse(before, after)
+    return verify
+
+
+def add_verify(text: str, block: str):
+    """verify() for appending `block` to `text` (see remove_verify)."""
+    parse = fs.toml_verify()
+
+    def verify(before: str, after: str) -> str:
+        if before != text:
+            raise ValueError("file changed since it was read")
+        if not (after.startswith(before) and after.endswith(block.rstrip("\n") + "\n")):
+            raise ValueError("result differs from the one-block append")
+        return parse(before, after)
+    return verify
+
+
+def _read(config: Path) -> str:
+    """The file's exact text: read_text would turn CRLF into LF and break byte-identity."""
+    return config.read_bytes().decode("utf-8")
+
+
+def codex_mcp_remove(config: Path, name: str, dry_run: bool = False) -> str | None:
+    text = _read(config)
+    span = toml_block(text, name)
+    if span is None:
+        return None
+    lines = text.splitlines(keepends=True)
+    block = "".join(lines[span[0]:span[1]])
+    if dry_run:
+        return block
+    after = "".join(lines[:span[0]] + lines[span[1]:])
+    fs.checked_write(config, after, remove_verify(text, name, block))   # WriteError, rolled back
+    return block
+
+
+def codex_mcp_add(config: Path, block: str) -> None:
+    text = _read(config) if config.exists() else ""
+    read = text
+    if text and not text.endswith("\n"):
+        text += "\n"
+    # Removal leaves the blank line that separated the block from its neighbour;
+    # not adding a second one makes disable -> enable byte-identical for a last block.
+    sep = "" if not text or re.search(r"\n\r?\n\Z", text) else "\n"
+    after = text + sep + block.rstrip("\n") + "\n"
+    fs.checked_write(config, after, add_verify(read, block))   # raises fs.WriteError, rolled back

agent_toggle/backends/plugin_cli.py

@@ -0,0 +1,41 @@
+"""Claude CLI access: binary lookup and the subprocess runner.
+
+`which` and `runner` are module-level hooks so tests can stub them and never
+spawn the real claude CLI.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+from .. import fs
+
+which = shutil.which
+runner = subprocess.run
+
+
+def claude_bin() -> str | None:
+    """Find the claude CLI. It is often absent from a hook/agent PATH."""
+    found = which("claude")
+    if found:
+        return found
+    home = fs.home()
+    for cand in (home / ".local/bin/claude", home / ".claude/local/claude"):
+        if cand.is_file() and os.access(cand, os.X_OK):
+            return str(cand)
+    return None
+
+
+def run_cli(binary: str | None, args: list[str], cwd: str | None = None) -> tuple[bool, str]:
+    """Run a harness CLI. `cwd` matters: `claude mcp -s local` is per-project."""
+    if not binary:
+        return False, "CLI not found on PATH"
+    try:
+        p = runner([binary, *args], capture_output=True, text=True,
+                   timeout=120, cwd=cwd)
+    except subprocess.TimeoutExpired:
+        return False, "CLI timed out after 120s"
+    except OSError as e:                     # cwd gone, binary unexecutable
+        return False, f"cannot run CLI{f' in {cwd}' if cwd else ''}: {e}"
+    return p.returncode == 0, (p.stdout + p.stderr).strip()