caura-bus-cli 0.3.0__py3-none-any.whl

caura_bus_cli/__init__.py

@@ -0,0 +1,5 @@
+"""caura-bus operator CLI."""
+
+from .main import app
+
+__all__ = ["app"]

caura_bus_cli/broker.py

@@ -0,0 +1,140 @@
+"""Prefer the Caura broker (`caura agent connect`) when it is installed.
+
+The broker connects an agent with a browser sign-in, keeps the agent key in
+the OS keychain and owns the runtime wiring, peer instructions and wake-ups.
+`caura-bus join` stays for hosts without it.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .join import JoinError, default_name, detect_runtime, sanitize_name
+
+BROKER = "caura"
+THREAD_PLACEHOLDER = "<CODEX_THREAD_ID>"
+BROKER_RUNTIMES = {"claude": "claude-code", "codex": "codex"}
+
+
+@dataclass
+class Broker:
+    path: str
+    # Flags `caura agent connect` accepts, e.g. {"agent", "runtime", "description"}.
+    flags: set[str] = field(default_factory=set)
+
+
+def _connect_flags(usage: str) -> set[str]:
+    flags = set()
+    for line in usage.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("-"):
+            flags.add(stripped.lstrip("-").split()[0])
+    return flags
+
+
+def find_broker(
+    which: Callable[[str], str | None] = shutil.which,
+    run: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+) -> Broker | None:
+    """The `caura` broker on PATH, if it is one that has `agent connect`."""
+    path = which(BROKER)
+    if not path:
+        return None
+    try:
+        probe = run(
+            [path, "agent", "connect", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+            stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    flags = _connect_flags((probe.stdout or "") + (probe.stderr or ""))
+    if not {"agent", "runtime", "project", "url"} <= flags:
+        return None
+    return Broker(path=path, flags=flags)
+
+
+@dataclass
+class BrokerPlan:
+    argv: list[str]
+    notes: list[str]
+    runnable: bool
+
+
+def connect_plan(
+    broker: Broker,
+    *,
+    url: str,
+    runtime: str,
+    directory: Path,
+    name: str | None,
+    description: str | None,
+    tenant: str | None,
+    hooks: bool,
+    memory: bool = True,
+    env: Mapping[str, str] | None = None,
+    ancestor: Callable[[], str | None] | None = None,
+) -> BrokerPlan:
+    """The `caura agent connect` command equivalent to these join options."""
+    env = os.environ if env is None else env
+    resolved = detect_runtime(runtime, env, ancestor) if ancestor else detect_runtime(runtime, env)
+    directory = directory.expanduser().resolve()
+    agent = sanitize_name(name) if name else ""
+    if name and not agent:
+        raise JoinError(f"--name {name!r} has no usable characters (use a-z, 0-9 and -)")
+    agent = agent or default_name(resolved, directory)
+    argv = [
+        broker.path,
+        "agent",
+        "connect",
+        "--runtime",
+        BROKER_RUNTIMES[resolved],
+        "--agent",
+        agent,
+        "--project",
+        str(directory),
+        "--url",
+        url,
+    ]
+    notes: list[str] = []
+    runnable = True
+    if resolved == "codex":
+        thread = env.get("CODEX_THREAD_ID", "")
+        if not thread:
+            thread, runnable = THREAD_PLACEHOLDER, False
+            notes.append(
+                "Codex needs its thread: run this inside the Codex session or replace the placeholder."
+            )
+        argv += ["--thread", thread]
+    if description is not None:
+        if "description" in broker.flags:
+            argv += ["--description", description]
+        else:
+            notes.append("This broker cannot register a description; set it later with peer op=describe.")
+    if tenant:
+        notes.append("--tenant is not passed: the broker uses the workspace you approve in the browser.")
+    if not hooks:
+        notes.append("--no-hooks is not passed: the broker always installs wake-ups.")
+    # A broker that knows --no-memory also registers the server's memory MCP.
+    if "no-memory" in broker.flags:
+        if not memory:
+            argv.append("--no-memory")
+    elif memory:
+        notes.append(
+            "This broker does not register the Caura memory MCP; upgrade it, or use "
+            "`caura-bus join --no-broker` to get the memory server wired too."
+        )
+    return BrokerPlan(argv=argv, notes=notes, runnable=runnable)
+
+
+def interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()

caura_bus_cli/hooks.py

@@ -0,0 +1,115 @@
+"""Merge native runtime hooks without replacing unrelated project settings."""
+
+import json
+import shlex
+import shutil
+import sys
+from pathlib import Path
+
+# Background listener lifetime per arming. A Stop re-arms it after every turn,
+# but an idle session has no turns: a short window left an open session deaf
+# after one quiet night. The listener already exits with its Claude Code
+# process, so the window only bounds a session left idle for a week.
+DEFAULT_LISTEN_SECONDS = 7 * 24 * 3600
+MAX_LISTEN_SECONDS = DEFAULT_LISTEN_SECONDS
+
+
+def install_hooks(
+    scope="project",
+    project=None,
+    config=None,
+    state=None,
+    listen_seconds=DEFAULT_LISTEN_SECONDS,
+    idle_listen_seconds=None,
+    shared=False,
+    key_file=None,
+):
+    """Install the Claude Code wake hooks.
+
+    SessionStart and Stop start a background ``asyncRewake`` listener: Claude
+    Code does not wait for it, and when it exits 2 Claude starts a new turn
+    with the wake text, also when the session is idle. UserPromptSubmit adds a
+    quick check to every human turn. ``idle_listen_seconds`` is accepted for
+    compatibility with older callers and ignored.
+    """
+    del idle_listen_seconds
+    root = Path(project or Path.cwd()) if scope == "project" else Path.home()
+    if shared and scope != "project":
+        raise ValueError("--shared applies only to --scope project")
+    filename = "settings.local.json" if scope == "project" and not shared else "settings.json"
+    path = root / ".claude" / filename
+    settings = json.loads(path.read_text()) if path.exists() else {}
+    hooks = settings.setdefault("hooks", {})
+    executable = shutil.which("caura-bus") or sibling_executable()
+    if not executable:
+        raise RuntimeError("caura-bus must be installed on PATH before installing hooks")
+    base = [str(Path(executable).absolute()), "recv", "--brief"]
+    if config:
+        base.extend(["--config", str(Path(config).resolve())])
+    if state:
+        base.extend(["--state", str(Path(state).resolve())])
+    if key_file:
+        base.extend(["--key-file", str(Path(key_file).resolve())])
+    listener = [*base, "--hook", "Rewake", "--wait", str(listen_seconds)]
+    entries_by_event = {
+        "SessionStart": {
+            "type": "command",
+            "command": shlex.join(listener),
+            "asyncRewake": True,
+            "timeout": listen_seconds + 60,
+        },
+        "Stop": {
+            "type": "command",
+            "command": shlex.join(listener),
+            "asyncRewake": True,
+            "timeout": listen_seconds + 60,
+        },
+        "UserPromptSubmit": {
+            "type": "command",
+            "command": shlex.join([*base, "--hook", "UserPromptSubmit"]),
+            "timeout": 10,
+        },
+    }
+    written = {}
+    # Drop our entries everywhere first, so a reinstall also removes hooks an
+    # older version installed under events it no longer uses.
+    for event, entries in list(hooks.items()):
+        if not isinstance(entries, list):
+            continue
+        owned = False
+        for group in entries:
+            kept = [h for h in group.get("hooks", []) if not owned_command(h.get("command", ""))]
+            owned = owned or len(kept) != len(group.get("hooks", []))
+            group["hooks"] = kept
+        if owned:
+            entries[:] = [group for group in entries if group.get("hooks")]
+            if not entries:
+                del hooks[event]
+    for event, hook in entries_by_event.items():
+        entry = {"hooks": [hook]}
+        hooks.setdefault(event, []).append(entry)
+        written[event] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(".json.tmp")
+    temporary.write_text(json.dumps(settings, indent=2) + "\n")
+    temporary.replace(path)
+    return {"path": str(path), "hooks": written}
+
+
+def sibling_executable():
+    """caura-bus next to the running interpreter (a venv or pipx install not on PATH)."""
+    candidate = Path(sys.executable).parent / "caura-bus"
+    return str(candidate) if candidate.is_file() else None
+
+
+def owned_command(command):
+    try:
+        parts = shlex.split(command)
+    except ValueError:
+        return False
+    return (
+        len(parts) >= 3
+        and Path(parts[0]).name == "caura-bus"
+        and parts[1:3] == ["recv", "--brief"]
+        and "--hook" in parts
+    )