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

caura_bus_cli/setup.py

@@ -0,0 +1,819 @@
+"""`caura-bus setup`: connect a Claude Code or Codex runtime to Caura in one step.
+
+Everything identity-related comes from the server: the key is verified first and
+the effective agent and tenant are read back from it. Each step only rewrites
+what setup owns (its agent config, the ``caura-bus`` MCP entry, the same
+server's ``caura`` memory MCP entry, and a marked instruction block), so
+re-running updates in place.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tomllib
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+from caura_bus_core import AgentConfig, Bus, PlatformError, load_config
+
+SERVER_NAME = "caura-bus"
+# The memory MCP of the same Caura server. Claude Code gets a local-scope
+# ``caura`` entry, which overrides a user-scope one of the same name in this
+# project. Codex has only a per-user config, so its entry is named per host.
+MEMORY_SERVER_NAME = "caura"
+MEMORY_PATH = "/mcp/"
+MEMORY_HEADER = "X-API-Key"
+# Entry names that usually hold a memory server pointing at some Caura.
+MEMORY_LIKE_NAMES = ("caura", "memclaw")  # legacy-name-floor: users' pre-rename MCP entry name
+MARK_START = "<!-- caura-bus:peer-instructions:start"
+MARK_END = "<!-- caura-bus:peer-instructions:end -->"
+MARK_HEADER = MARK_START + " (managed by `caura-bus setup`; re-running setup replaces this block) -->"
+LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+RUNTIMES = {"claude": "claude", "claude-code": "claude", "codex": "codex"}
+INSTRUCTION_FILES = {"claude": "CLAUDE.md", "codex": "AGENTS.md"}
+RUNTIME_NAMES = {"claude": "Claude Code", "codex": "Codex"}
+NEXT_HEADER = re.compile(r"^[ \t]*\[", re.M)
+OWNED_KEYS = re.compile(r"^[ \t]*(?:command|args|env)[ \t]*=")
+MEMORY_OWNED_KEYS = re.compile(r"^[ \t]*(?:url|http_headers|command|args|env)[ \t]*=")
+
+
+def codex_header(name: str) -> re.Pattern[str]:
+    quoted = re.escape(name)
+    return re.compile(rf'^\[\s*mcp_servers\s*\.\s*(?:"{quoted}"|{quoted})\s*\]\s*(?:#.*)?$', re.M)
+
+
+CODEX_HEADER = codex_header(SERVER_NAME)
+
+
+class SetupError(RuntimeError):
+    """A step failed; the message is safe to print (keys are masked)."""
+
+
+def mask(key: str) -> str:
+    key = key.strip()
+    return f"{key[:6]}…{key[-4:]}" if len(key) >= 16 else "****"
+
+
+def scrub(text: str, key: str) -> str:
+    return text.replace(key, mask(key)) if key else text
+
+
+def show(path: Path | str) -> str:
+    """Shorten a path under HOME to ~/... for display (never for commands with VAR=path)."""
+    text, home = str(path), str(Path.home())
+    return "~" + text[len(home) :] if text == home or text.startswith(home + os.sep) else text
+
+
+def shell_path(path: Path) -> str:
+    """A shell word for ``path``, keeping a leading ~/ expandable."""
+    shown = show(path)
+    return "~/" + shlex.quote(shown[2:]) if shown.startswith("~/") else shlex.quote(shown)
+
+
+def toml_str(value: str) -> str:
+    # JSON string escapes (\" \\ \n \uXXXX ...) are valid TOML basic-string escapes.
+    return json.dumps(value)
+
+
+def check_url(url: str) -> tuple[str, bool]:
+    """Return the normalised origin and whether plain HTTP is allowed (localhost only)."""
+    parts = urlsplit(url.strip())
+    if parts.scheme not in {"https", "http"} or not parts.hostname:
+        raise SetupError(f"--url must be an http(s) origin such as https://caura.example, got {url!r}")
+    if parts.path not in {"", "/"} or parts.query or parts.fragment or parts.username or parts.password:
+        raise SetupError(
+            "--url must be the gateway origin only (no path such as /api/v1, query or credentials)"
+        )
+    insecure = parts.scheme == "http"
+    if insecure and parts.hostname not in LOCAL_HOSTS:
+        raise SetupError("plain http is allowed only for localhost; use https://")
+    return f"{parts.scheme}://{parts.netloc}", insecure
+
+
+def slug(value: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]", "_", value).strip(".") or "_"
+
+
+def config_home() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    return Path(base) if base else Path.home() / ".config"
+
+
+def default_config_path(url: str, tenant_id: str, agent_id: str) -> Path:
+    netloc = urlsplit(url).netloc
+    return config_home() / "caura-bus" / "agents" / slug(netloc) / slug(tenant_id) / f"{slug(agent_id)}.toml"
+
+
+def codex_config_path() -> Path:
+    base = os.environ.get("CODEX_HOME", "").strip()
+    return (Path(base) if base else Path.home() / ".codex") / "config.toml"
+
+
+def find_mcp_binary() -> Path | None:
+    """Prefer the caura-bus-mcp installed next to this CLI (same version), then PATH."""
+    sibling = Path(sys.executable).parent / "caura-bus-mcp"
+    if sibling.is_file() and os.access(sibling, os.X_OK):
+        return sibling.absolute()
+    found = shutil.which("caura-bus-mcp")
+    return Path(found).absolute() if found else None
+
+
+def peer_template() -> str:
+    return files("caura_bus_cli").joinpath("peer_instructions.md").read_text()
+
+
+# --- 1. verify the key ----------------------------------------------------
+
+
+async def verify(url: str, insecure: bool, key: str, transport: httpx.AsyncBaseTransport | None = None):
+    """Read the effective identity, then re-check it the way `doctor` does."""
+    probe = AgentConfig(
+        api_url=url,
+        allow_insecure_http=insecure,
+        agent={"agent_id": "unverified", "tenant_id": "unverified"},
+    )
+    bus = Bus(probe, api_key=key, transport=transport)
+    try:
+        identity = await bus.request("GET", "identity")
+    finally:
+        await bus.close()
+    if not isinstance(identity, dict) or not identity.get("agent_id") or not identity.get("tenant_id"):
+        raise SetupError("the server did not return an agent identity; is --url a Caura gateway?")
+    return identity
+
+
+async def describe(config: AgentConfig, key: str, text: str, transport=None) -> dict:
+    async with Bus(config, api_key=key, transport=transport) as bus:
+        return await bus.describe(text)
+
+
+# --- 2. agent config ------------------------------------------------------
+
+
+def render_config(url: str, insecure: bool, identity: dict, existing: Path) -> str:
+    peers: list[str] = ["*"]
+    consultation: dict[str, Any] = {}
+    if existing.is_file():
+        try:
+            old = tomllib.loads(existing.read_text())
+        except (tomllib.TOMLDecodeError, OSError):
+            old = {}
+        if isinstance(old.get("peers"), list):
+            peers = [str(p) for p in old["peers"]]
+        if isinstance(old.get("consultation"), dict):
+            consultation = old["consultation"]
+    lines = [
+        "# Managed by `caura-bus setup`; re-run it to update. The API key is not stored here.",
+        f"api_url = {toml_str(url)}",
+    ]
+    if insecure:
+        lines.append("allow_insecure_http = true")
+    lines.append("peers = [" + ", ".join(toml_str(p) for p in peers) + "]")
+    lines += [
+        "",
+        "[agent]",
+        f"agent_id = {toml_str(identity['agent_id'])}",
+        f"tenant_id = {toml_str(identity['tenant_id'])}",
+    ]
+    if identity.get("fleet_id"):
+        lines.append(f"fleet_id = {toml_str(str(identity['fleet_id']))}")
+    if consultation:
+        lines += ["", "[consultation]"]
+        for name in ("max_requests", "deadline_seconds"):
+            if isinstance(consultation.get(name), int | float) and not isinstance(
+                consultation.get(name), bool
+            ):
+                lines.append(f"{name} = {consultation[name]}")
+    return "\n".join(lines) + "\n"
+
+
+def write_private(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    temporary = path.with_name(path.name + ".tmp")
+    fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as handle:
+        handle.write(text)
+    os.chmod(temporary, 0o600)
+    temporary.replace(path)
+
+
+# --- 3. runtime wiring ----------------------------------------------------
+
+
+def claude_add_argv(claude: str, key: str, config: Path, mcp: Path) -> list[str]:
+    return [
+        claude,
+        "mcp",
+        "add",
+        "--scope",
+        "local",
+        SERVER_NAME,
+        "-e",
+        f"CAURA_API_KEY={key}",
+        "-e",
+        f"CAURA_BUS_AGENT_CONFIG={config}",
+        "--",
+        str(mcp),
+    ]
+
+
+def claude_manual_command(directory: Path, config: Path, mcp: Path) -> str:
+    """The exact command to run by hand; the key comes from the user's environment."""
+    argv = claude_add_argv("claude", "KEYPLACEHOLDER", config, mcp)
+    command = shlex.join(argv).replace(
+        "CAURA_API_KEY=KEYPLACEHOLDER", '"CAURA_API_KEY=${CAURA_API_KEY:?export your agent key first}"'
+    )
+    return f"cd {shlex.quote(str(directory))} && {command}"
+
+
+def wire_claude(directory: Path, key: str, config: Path, mcp: Path) -> str:
+    claude = shutil.which("claude")
+    if not claude:
+        raise SetupError(
+            "`claude` is not on PATH. Run this yourself (with CAURA_API_KEY exported):\n  "
+            + claude_manual_command(directory, config, mcp)
+        )
+    # Replace a previous entry so re-running updates the key and paths in place.
+    subprocess.run(
+        [claude, "mcp", "remove", "--scope", "local", SERVER_NAME],
+        cwd=directory,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    result = subprocess.run(
+        claude_add_argv(claude, key, config, mcp),
+        cwd=directory,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = scrub((result.stderr or result.stdout).strip(), key)
+        raise SetupError(f"`claude mcp add` failed ({result.returncode}): {detail}")
+    return f"claude mcp add --scope local {SERVER_NAME} (project {show(directory)})"
+
+
+def codex_block(key: str, config: Path, mcp: Path) -> list[str]:
+    return [
+        f"command = {toml_str(str(mcp))}",
+        "env = { CAURA_API_KEY = "
+        + toml_str(key)
+        + ", CAURA_BUS_AGENT_CONFIG = "
+        + toml_str(str(config))
+        + " }",
+    ]
+
+
+def without_table(data: dict, name: str, owned: tuple[str, ...]) -> dict:
+    data = json.loads(json.dumps(data, default=str))
+    entry = data.get("mcp_servers", {}).get(name)
+    if isinstance(entry, dict):
+        for key in owned:
+            entry.pop(key, None)
+        if not entry:
+            data["mcp_servers"].pop(name)
+        if not data["mcp_servers"]:
+            data.pop("mcp_servers")
+    return data
+
+
+@dataclass
+class CodexTable:
+    """One ``[mcp_servers.<name>]`` table setup owns some keys of."""
+
+    name: str
+    lines: list[str]
+    owned: tuple[str, ...]
+    owned_pattern: re.Pattern[str]
+    expected: dict[str, Any]
+
+
+def bus_table(key: str, config: Path, mcp: Path) -> CodexTable:
+    return CodexTable(
+        name=SERVER_NAME,
+        lines=codex_block(key, config, mcp),
+        owned=("command", "args", "env"),
+        owned_pattern=OWNED_KEYS,
+        expected={"command": str(mcp), "env": {"CAURA_API_KEY": key, "CAURA_BUS_AGENT_CONFIG": str(config)}},
+    )
+
+
+def memory_table(url: str, key: str) -> CodexTable:
+    endpoint = memory_url(url)
+    return CodexTable(
+        name=codex_memory_name(url),
+        lines=[
+            f"url = {toml_str(endpoint)}",
+            "http_headers = { " + toml_str(MEMORY_HEADER) + " = " + toml_str(key) + " }",
+        ],
+        owned=("url", "http_headers", "command", "args", "env"),
+        owned_pattern=MEMORY_OWNED_KEYS,
+        expected={"url": endpoint, "http_headers": {MEMORY_HEADER: key}},
+    )
+
+
+def update_codex_table(text: str, table: CodexTable) -> str:
+    """Add or update only [mcp_servers.<name>]; refuse anything that would change more."""
+    name = table.name
+    try:
+        before = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise SetupError(f"existing Codex config is not valid TOML ({exc}); not modified") from None
+    match = codex_header(name).search(text)
+    if match is None:
+        if name in before.get("mcp_servers", {}):
+            raise SetupError(
+                f"Codex config defines mcp_servers.{name} without a [mcp_servers.{name}] "
+                "table header; edit it by hand or move it into that table, then re-run setup"
+            )
+        updated = (text.rstrip("\n") + "\n\n" if text.strip() else "") + "\n".join(
+            [f"[mcp_servers.{name}]", *table.lines]
+        )
+        updated += "\n"
+    else:
+        start = match.end() + 1 if match.end() < len(text) else match.end()
+        following = NEXT_HEADER.search(text, start)
+        end = following.start() if following else len(text)
+        kept = [line for line in text[start:end].splitlines() if not table.owned_pattern.match(line)]
+        body = "\n".join([*table.lines, *kept]).rstrip("\n") + "\n"
+        if following:
+            body += "\n"
+        prefix = text[:start] if text[:start].endswith("\n") else text[:start] + "\n"
+        updated = prefix + body + text[end:].lstrip("\n")
+    try:
+        after = tomllib.loads(updated)
+    except tomllib.TOMLDecodeError as exc:
+        raise SetupError(
+            f"updating [mcp_servers.{name}] would produce invalid TOML ({exc}); the table probably "
+            "uses multi-line values or a separate sub-table for a key setup manages. Not modified."
+        ) from None
+    entry = after.get("mcp_servers", {}).get(name, {})
+    unexpected = [key for key in table.owned if key not in table.expected and key in entry]
+    if any(entry.get(key) != value for key, value in table.expected.items()) or unexpected:
+        raise SetupError(f"could not verify the updated [mcp_servers.{name}] table; not modified")
+    if without_table(before, name, table.owned) != without_table(after, name, table.owned):
+        raise SetupError("updating the Codex config would change other settings; not modified")
+    return updated
+
+
+def update_codex_text(text: str, key: str, config: Path, mcp: Path) -> str:
+    return update_codex_table(text, bus_table(key, config, mcp))
+
+
+def wire_codex(tables: list[CodexTable], path: Path | None = None) -> list[str]:
+    """Update every table in one write, with one backup of the previous file."""
+    path = path or codex_config_path()
+    text = path.read_text() if path.exists() else ""
+    updated = text
+    for table in tables:
+        updated = update_codex_table(updated, table)
+    names = ", ".join(f"[mcp_servers.{table.name}]" for table in tables)
+    if updated == text:
+        return [f"{names} already current in {show(path)}"]
+    if path.exists():
+        backup = path.with_name(path.name + ".caura-bus-setup.bak")
+        shutil.copy2(path, backup)
+        os.chmod(backup, 0o600)
+    write_private(path, updated)  # it now holds an agent key
+    return [
+        f"{names} written to {show(path)}" + (f" (backup {path.name}.caura-bus-setup.bak)" if text else "")
+    ]
+
+
+# --- 3b. memory MCP of the same server -----------------------------------
+
+
+def memory_url(url: str) -> str:
+    return url.rstrip("/") + MEMORY_PATH
+
+
+def host_slug(url: str) -> str:
+    netloc = urlsplit(url).netloc.lower()
+    return re.sub(r"-{2,}", "-", re.sub(r"[^a-z0-9]+", "-", netloc)).strip("-") or "host"
+
+
+def codex_memory_name(url: str) -> str:
+    return f"{MEMORY_SERVER_NAME}-{host_slug(url)}"
+
+
+def memory_like(name: str) -> bool:
+    lowered = name.lower()
+    return any(lowered == base or lowered.startswith(base + "-") for base in MEMORY_LIKE_NAMES)
+
+
+def entry_target(entry: Any) -> str | None:
+    """The host an MCP entry talks to, ``""`` for a command we cannot read, None if not an entry."""
+    if not isinstance(entry, dict):
+        return None
+    target = entry.get("url")
+    if isinstance(target, str) and target:
+        return (urlsplit(target).hostname or target).lower()
+    return "" if entry.get("command") else None
+
+
+def other_memory_entries(servers: Any, ours: str, url: str) -> list[str]:
+    """Describe memory-like entries other than ``ours`` that do not point at this server."""
+    if not isinstance(servers, dict):
+        return []
+    host = (urlsplit(url).hostname or "").lower()
+    found = []
+    for name, entry in servers.items():
+        if name == ours or name == SERVER_NAME or not memory_like(str(name)):
+            continue
+        target = entry_target(entry)
+        if target is None or target == host:
+            continue
+        if target == "":
+            if str(name).lower().startswith(MEMORY_SERVER_NAME + "-"):
+                continue  # caura-bus and friends: local commands, not memory servers
+            found.append(f"{name!r} (a local command; cannot tell which server it uses)")
+        else:
+            found.append(f"{name!r} -> {target}")
+    return found
+
+
+def claude_config_file() -> Path:
+    base = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    return (Path(base) if base else Path.home()) / ".claude.json"
+
+
+def read_json(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def claude_memory_warnings(directory: Path, url: str) -> list[str]:
+    """Memory-like Claude Code entries that would still be loaded here and point elsewhere."""
+    warnings = []
+    user = other_memory_entries(read_json(claude_config_file()).get("mcpServers"), "", url)
+    for item in user:
+        overridden = item.startswith(repr(MEMORY_SERVER_NAME) + " ")
+        warnings.append(
+            f"user-scope MCP server {item}"
+            + (
+                f" is overridden in this project by the local {MEMORY_SERVER_NAME!r} entry"
+                if overridden
+                else ": still loaded in this project, so the agent may save memories there"
+            )
+        )
+    project = other_memory_entries(read_json(directory / ".mcp.json").get("mcpServers"), "", url)
+    for item in project:
+        overridden = item.startswith(repr(MEMORY_SERVER_NAME) + " ")
+        warnings.append(
+            f"project .mcp.json server {item}"
+            + (" is overridden by the local entry" if overridden else ": the agent may save memories there")
+        )
+    return warnings
+
+
+def codex_memory_warnings(text: str, url: str) -> list[str]:
+    try:
+        servers = tomllib.loads(text).get("mcp_servers")
+    except tomllib.TOMLDecodeError:
+        return []
+    return [
+        f"Codex MCP server {item}: Codex loads it too, so the agent may save memories there"
+        for item in other_memory_entries(servers, codex_memory_name(url), url)
+    ]
+
+
+def claude_memory_argv(claude: str, url: str, key: str) -> list[str]:
+    # --header is variadic, so it goes after the name and URL.
+    return [
+        claude,
+        "mcp",
+        "add",
+        "--scope",
+        "local",
+        "--transport",
+        "http",
+        MEMORY_SERVER_NAME,
+        memory_url(url),
+        "--header",
+        f"{MEMORY_HEADER}: {key}",
+    ]
+
+
+def claude_memory_manual_command(directory: Path, url: str) -> str:
+    command = shlex.join(claude_memory_argv("claude", url, "KEYPLACEHOLDER")).replace(
+        f"'{MEMORY_HEADER}: KEYPLACEHOLDER'",
+        f'"{MEMORY_HEADER}: ${{CAURA_API_KEY:?export your agent key first}}"',
+    )
+    return f"cd {shlex.quote(str(directory))} && {command}"
+
+
+def wire_claude_memory(directory: Path, url: str, key: str) -> str:
+    claude = shutil.which("claude")
+    if not claude:
+        raise SetupError(
+            "`claude` is not on PATH. Run this yourself (with CAURA_API_KEY exported):\n  "
+            + claude_memory_manual_command(directory, url)
+        )
+    subprocess.run(
+        [claude, "mcp", "remove", "--scope", "local", MEMORY_SERVER_NAME],
+        cwd=directory,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    result = subprocess.run(
+        claude_memory_argv(claude, url, key), cwd=directory, capture_output=True, text=True, check=False
+    )
+    if result.returncode != 0:
+        detail = scrub((result.stderr or result.stdout).strip(), key)
+        raise SetupError(f"`claude mcp add` for the memory server failed ({result.returncode}): {detail}")
+    return (
+        f"claude mcp add --scope local --transport http {MEMORY_SERVER_NAME} {memory_url(url)} "
+        f"(project {show(directory)}; the key is stored in {show(claude_config_file())})"
+    )
+
+
+# --- 4. peer instructions -------------------------------------------------
+
+
+def instruction_block() -> str:
+    return f"{MARK_HEADER}\n{peer_template().rstrip()}\n{MARK_END}\n"
+
+
+def merge_instructions(existing: str | None) -> tuple[str, str]:
+    block = instruction_block()
+    if existing is None:
+        return block, "created"
+    start = existing.find(MARK_START)
+    if start != -1:
+        end = existing.find(MARK_END, start)
+        if end == -1:
+            raise SetupError(f"found the {MARK_START} marker without its end marker; fix the file by hand")
+        end += len(MARK_END)
+        if existing[end : end + 1] == "\n":
+            end += 1
+        updated = existing[:start] + block + existing[end:]
+        return updated, "unchanged" if updated == existing else "updated"
+    if not existing or existing.endswith("\n\n"):
+        separator = ""
+    else:
+        separator = "\n" if existing.endswith("\n") else "\n\n"
+    return existing + separator + block, "appended"
+
+
+def write_instructions(path: Path) -> str:
+    existing = path.read_text() if path.exists() else None
+    updated, action = merge_instructions(existing)
+    if action != "unchanged":
+        temporary = path.with_name(path.name + ".tmp")
+        temporary.write_text(updated)
+        if path.exists():
+            os.chmod(temporary, path.stat().st_mode & 0o777)
+        temporary.replace(path)
+    return action
+
+
+# --- 5. wake-ups (opt-in) -----------------------------------------------
+
+
+def key_file_path(config: Path) -> Path:
+    return config.with_suffix(".key")
+
+
+def codex_waker_command(directory: Path, config: Path, key_file: Path) -> str:
+    return shlex.join(
+        [
+            "caura-bus",
+            "wake",
+            "--runtime",
+            "codex",
+            "--thread",
+            "latest",
+            "--dir",
+            str(directory),
+            "--config",
+            str(config),
+            "--key-file",
+            str(key_file),
+        ]
+    )
+
+
+def install_wake(options, runtime, directory, config_path, key, echo) -> str | None:
+    """Store the key for hooks/wakers (0600) and install Claude hooks or print the Codex waker.
+
+    Hooks and wakers are started by the runtime, not by the shell that holds
+    CAURA_API_KEY, so they read the key from a private file next to the config.
+    """
+    from .hooks import install_hooks
+
+    key_file = key_file_path(config_path)
+    prefix = "[dry-run] would " if options.dry_run else ""
+    if options.dry_run:
+        echo(f"  {prefix}write the agent key to {show(key_file)} (mode 600) for wake-ups")
+    else:
+        write_private(key_file, key + "\n")
+        echo(f"  [ok] agent key for wake-ups {show(key_file)} (mode 600)")
+    if runtime == "codex":
+        command = codex_waker_command(directory, config_path, key_file)
+        echo(f"  {prefix if options.dry_run else '[ok] '}Codex wake-ups: run `{command}` while Codex is open")
+        return command
+    if options.dry_run:
+        echo(f"  {prefix}install Claude Code wake hooks in {show(directory / '.claude/settings.local.json')}")
+        return None
+    try:
+        result = install_hooks(project=directory, config=config_path, key_file=key_file)
+    except (RuntimeError, ValueError, OSError) as exc:
+        echo(f"  [!!] wake hooks not installed: {exc}")
+        return None
+    echo(f"  [ok] wake hooks {show(result['path'])} (SessionStart/Stop listener, UserPromptSubmit check)")
+    return None
+
+
+# --- orchestration --------------------------------------------------------
+
+
+@dataclass
+class Options:
+    runtime: str
+    url: str
+    key: str
+    directory: Path
+    agent_id: str | None = None
+    description: str | None = None
+    config: Path | None = None
+    dry_run: bool = False
+    hooks: bool = False
+    codex_config: Path | None = None
+    # Also register this server's memory MCP (`caura`), so durable memories land here.
+    memory: bool = True
+    transport: httpx.AsyncBaseTransport | None = field(default=None, repr=False)
+    # `join` prints its own next steps; it reads back what setup wrote.
+    next_steps: bool = True
+    config_path: Path | None = field(default=None, init=False)
+    waker: str | None = field(default=None, init=False)
+
+
+def run_setup(options: Options, echo: Callable[[str], None], run_async) -> int:
+    runtime = RUNTIMES.get(options.runtime)
+    if runtime is None:
+        raise SetupError("--runtime must be claude or codex")
+    key = options.key.strip()
+    if not key:
+        raise SetupError("an agent key is required (--key or CAURA_API_KEY)")
+    url, insecure = check_url(options.url)
+    directory = options.directory.expanduser().resolve()
+    if not directory.is_dir():
+        raise SetupError(f"--dir {directory} is not a directory")
+    prefix = "[dry-run] would " if options.dry_run else ""
+    echo(f"Connecting {RUNTIME_NAMES[runtime]} in {show(directory)} to Caura at {url}")
+
+    try:
+        identity = run_async(verify(url, insecure, key, options.transport))
+    except PlatformError as exc:
+        if exc.status in {401, 403}:
+            raise SetupError(
+                f"the server rejected key {mask(key)} ({exc.status}); check it and --url"
+            ) from None
+        raise SetupError(scrub(str(exc), key)) from None
+    except httpx.HTTPError as exc:
+        raise SetupError(f"cannot reach {url}: {scrub(str(exc), key) or type(exc).__name__}") from None
+    agent_id, tenant_id = identity["agent_id"], identity["tenant_id"]
+    if options.agent_id and options.agent_id != agent_id:
+        raise SetupError(
+            f"key {mask(key)} belongs to agent {agent_id!r}, not {options.agent_id!r}; nothing was changed"
+        )
+    echo(f"  [ok] key {mask(key)} verified: agent {agent_id}, tenant {tenant_id}")
+
+    config_path = (options.config or default_config_path(url, tenant_id, agent_id)).expanduser().absolute()
+    options.config_path = config_path
+    text = render_config(url, insecure, identity, config_path)
+    AgentConfig.model_validate(tomllib.loads(text))
+    unchanged = config_path.is_file() and config_path.read_text() == text
+    if options.dry_run:
+        echo(f"  {prefix}write agent config {show(config_path)} (mode 600)")
+    else:
+        if not unchanged:
+            write_private(config_path, text)
+        os.chmod(config_path, 0o600)
+        load_config(config_path)
+        echo(f"  [ok] agent config {show(config_path)} (mode 600{', unchanged' if unchanged else ''})")
+
+    mcp = find_mcp_binary()
+    if mcp is None:
+        raise SetupError(
+            "caura-bus-mcp is not installed next to caura-bus or on PATH; install it "
+            "(it ships with caura-bus-cli) and re-run setup"
+        )
+    if runtime == "claude":
+        if options.dry_run:
+            echo(f"  {prefix}run in {directory}:")
+            echo("      " + shlex.join(claude_add_argv("claude", mask(key), config_path, mcp)))
+            if options.memory:
+                echo("      " + shlex.join(claude_memory_argv("claude", url, mask(key))))
+        else:
+            try:
+                echo("  [ok] MCP server " + wire_claude(directory, key, config_path, mcp))
+                if options.memory:
+                    echo("  [ok] memory MCP server " + wire_claude_memory(directory, url, key))
+            except SetupError as exc:
+                echo(f"  [!!] {exc}")
+                return finish(options, runtime, directory, config_path, echo, run_async, key, failed=True)
+        if options.memory:
+            for warning in claude_memory_warnings(directory, url):
+                echo(f"  [!!] {warning}")
+            echo(
+                f"       check which servers this project loads: cd {shell_path(directory)} && claude mcp list"
+            )
+    else:
+        codex_path = (options.codex_config or codex_config_path()).expanduser()
+        tables = [bus_table(key, config_path, mcp)]
+        if options.memory:
+            tables.append(memory_table(url, key))
+        current = codex_path.read_text() if codex_path.exists() else ""
+        if options.dry_run:
+            planned = current
+            for table in tables:
+                planned = update_codex_table(planned, table)
+            echo(
+                f"  {prefix}add/update [mcp_servers.{SERVER_NAME}] in {show(codex_path)} (backup kept, mode 600)"
+            )
+            echo(
+                f"      command = {mcp}; env CAURA_API_KEY={mask(key)}, CAURA_BUS_AGENT_CONFIG={config_path}"
+            )
+            if options.memory:
+                echo(f"  {prefix}add/update [mcp_servers.{codex_memory_name(url)}] in {show(codex_path)}")
+                echo(f"      url = {memory_url(url)}; http_headers {MEMORY_HEADER}={mask(key)}")
+        else:
+            for line in wire_codex(tables, codex_path):
+                echo("  [ok] MCP server" + ("s " if options.memory else " ") + line)
+        if options.memory:
+            for warning in codex_memory_warnings(current, url):
+                echo(f"  [!!] {warning}")
+            echo("       check which servers Codex loads: codex mcp list")
+    return finish(options, runtime, directory, config_path, echo, run_async, key, failed=False)
+
+
+def finish(options, runtime, directory, config_path, echo, run_async, key, *, failed) -> int:
+    prefix = "[dry-run] would " if options.dry_run else ""
+    instructions = directory / INSTRUCTION_FILES[runtime]
+    if options.dry_run:
+        _, action = merge_instructions(instructions.read_text() if instructions.exists() else None)
+        verb = {"created": "create", "appended": "append to", "updated": "update", "unchanged": "keep"}[
+            action
+        ]
+        echo(f"  {prefix}{verb} peer instructions in {show(instructions)}")
+    else:
+        echo(f"  [ok] peer instructions {show(instructions)} ({write_instructions(instructions)})")
+
+    if options.description is not None:
+        if options.dry_run:
+            echo(f"  {prefix}register description ({len(options.description)} chars)")
+        else:
+            try:
+                run_async(describe(load_config(config_path), key, options.description, options.transport))
+                echo("  [ok] description registered")
+            except PlatformError as exc:
+                note = "this server does not support descriptions yet" if exc.status == 404 else str(exc)
+                echo(f"  [!!] description not registered: {scrub(note, key)}")
+            except ValueError as exc:
+                echo(f"  [!!] description not registered: {exc}")
+
+    waker = None
+    if options.hooks:
+        waker = install_wake(options, runtime, directory, config_path, key, echo)
+    options.waker = waker
+
+    if options.dry_run:
+        echo("Dry run: nothing was written.")
+        return 0
+    if not options.next_steps:
+        return 1 if failed else 0
+    start = f"cd {shell_path(directory)} && {'claude' if runtime == 'claude' else 'codex'}"
+    echo("")
+    echo("Next steps:" if not failed else "Finish the MCP step above, then:")
+    if runtime == "claude":
+        echo(f"  1. Start Claude Code in the project:  {start}")
+    else:
+        echo(f"  1. Start (or restart) Codex in the project:  {start}")
+    if waker:
+        echo(f"     In another terminal, keep the wake listener running:  {waker}")
+    echo('  2. Try: "Use the caura-bus peer tool: discover available peers and tell me who they are."')
+    if options.memory:
+        listing = "claude mcp list" if runtime == "claude" else "codex mcp list"
+        echo(f"     Memory: `{listing}` should show this server's memory MCP ({memory_url(options.url)}).")
+    echo(
+        "  3. Check the connection any time:  CAURA_API_KEY=<your key> caura-bus doctor "
+        f"--config {shell_path(config_path)}"
+    )
+    return 1 if failed else 0