agent-brain-cli 10.3.2__tar.gz → 10.5.0__tar.gz

{agent_brain_cli-10.3.2 → agent_brain_cli-10.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-brain-cli
-Version: 10.3.2
+Version: 10.5.0
 Summary: Agent Brain CLI - Command-line interface for managing AI agent memory and knowledge retrieval
 Home-page: https://github.com/SpillwaveSolutions/agent-brain
 License: MIT
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: agent-brain-rag (>=10.3.2,<11.0.0)
+Requires-Dist: agent-brain-rag (>=10.4.0,<11.0.0)
 Requires-Dist: agent-brain-uds (>=10.3.0,<11.0.0)
 Requires-Dist: click (>=8.1.0,<9.0.0)
 Requires-Dist: httpx (>=0.28.0,<0.29.0)
@@ -23,6 +23,7 @@ Requires-Dist: psutil (>=6.0,<7.0)
 Requires-Dist: pydantic (>=2.10.0,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.0,<7.0.0)
 Requires-Dist: rich (>=13.9.0,<14.0.0)
+Requires-Dist: tomlkit (>=0.13.0,<0.14.0)
 Project-URL: Documentation, https://github.com/SpillwaveSolutions/agent-brain/wiki
 Project-URL: Repository, https://github.com/SpillwaveSolutions/agent-brain
 Description-Content-Type: text/markdown

{agent_brain_cli-10.3.2 → agent_brain_cli-10.5.0}/agent_brain_cli/__init__.py

@@ -1,3 +1,3 @@
 """Doc-Serve CLI - Command-line interface for managing Doc-Serve server."""
 
-__version__ = "10.3.2"
+__version__ = "10.5.0"

{agent_brain_cli-10.3.2 → agent_brain_cli-10.5.0}/agent_brain_cli/cli.py

@@ -12,6 +12,7 @@ from .commands import (
     config_group,
     doctor_command,
     folders_group,
+    graph_group,
     index_command,
     init_command,
     inject_command,
@@ -164,6 +165,9 @@ cli.add_command(mcp_group, name="mcp")
 cli.add_command(prompt_command, name="prompt")
 cli.add_command(resources_group, name="resources")
 
+# Register graph management commands
+cli.add_command(graph_group, name="graph")
+
 # Register server interaction commands
 cli.add_command(status_command, name="status")
 cli.add_command(query_command, name="query")

{agent_brain_cli-10.3.2 → agent_brain_cli-10.5.0}/agent_brain_cli/client/transport.py

@@ -186,7 +186,14 @@ def open_backend(ctx: click.Context, *, timeout: float = 30.0) -> BackendClient:
         # mcp_transport == "http" — resolve_mcp_transport guarantees
         # mcp_target is not None for the http branch.
         assert mcp_target is not None  # noqa: S101
-        return cast(BackendClient, McpHttpBackend(url=mcp_target, timeout=timeout))
+        # Thread state_dir so FileTokenStorage is keyed correctly when
+        # AGENT_BRAIN_MCP_AUTH=oauth is set (Phase 69 Plan 03).
+        # The opt-in flows via the AGENT_BRAIN_MCP_AUTH env var — no extra
+        # param needed here.
+        return cast(
+            BackendClient,
+            McpHttpBackend(url=mcp_target, timeout=timeout, state_dir=state_dir),
+        )
 
     # --- HTTP / UDS branch (existing v1/v2 path) -----------------
     transport, target = resolve_transport(

{agent_brain_cli-10.3.2 → agent_brain_cli-10.5.0}/agent_brain_cli/commands/__init__.py

@@ -4,6 +4,7 @@ from .cache import cache_group
 from .config import config_group
 from .doctor import doctor_command
 from .folders import folders_group
+from .graph import graph_group
 from .index import index_command
 from .init import init_command
 from .inject import inject_command
@@ -26,6 +27,7 @@ __all__ = [
     "config_group",
     "doctor_command",
     "folders_group",
+    "graph_group",
     "index_command",
     "inject_command",
     "init_command",

agent_brain_cli-10.5.0/agent_brain_cli/commands/graph.py

@@ -0,0 +1,154 @@
+"""`agent-brain graph` Click sub-group for graph management commands (Phase 64).
+
+Subcommands:
+    restore-from-snapshot — replay the latest (or a specific) kuzu snapshot
+        back into the live graph. Confirm-by-default; --yes skips the prompt
+        for non-interactive/CI use; --dry-run reports the plan without mutating.
+
+Closes #184 bug 1: when kuzu opens cleanly but the live graph is STALE after
+an AGENT_BRAIN_JOB_TIMEOUT rollback, operators can replay the latest valid
+snapshot to bring the graph back in sync.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from agent_brain_cli.config import STATE_DIR_NAME, resolve_project_root
+
+# Re-use diagnostics helpers for state-dir + store-type resolution and the
+# server-running guard. These are local imports inside the CLI so the module
+# loads without requiring the server package to be installed.
+from agent_brain_cli.diagnostics import (
+    _graph_index_dir,
+    _read_graphrag_block,
+    _server_is_running,
+)
+
+# agent-brain-rag is a declared dependency of agent-brain-cli (^10.x), so this
+# import is safe at module level. The lazy try/except below is a belt-and-braces
+# guard for edge cases where the server wheel is not installed in the env.
+try:
+    from agent_brain_server.storage.graph_store import GraphStoreManager
+except ImportError:  # pragma: no cover
+    GraphStoreManager = None
+
+console = Console()
+
+
+@click.group(name="graph")
+def graph_group() -> None:
+    """Manage the GraphRAG graph index (kuzu backend).
+
+    \b
+    Commands:
+      restore-from-snapshot  Replay a snapshot back into kuzu.
+    """
+
+
+@graph_group.command("restore-from-snapshot")
+@click.option(
+    "--snapshot",
+    "snapshot_path",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help=(
+        "Snapshot file to restore (default: latest valid snapshot on disk). "
+        "Must be a .json snapshot written by the agent-brain-server."
+    ),
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Report what would be restored and exit without mutating kuzu.",
+)
+@click.option(
+    "--yes",
+    "assume_yes",
+    is_flag=True,
+    help="Skip the confirmation prompt (non-interactive/CI use).",
+)
+def restore_from_snapshot(
+    snapshot_path: Path | None,
+    dry_run: bool,
+    assume_yes: bool,
+) -> None:
+    """Replay a kuzu snapshot back into the live graph.
+
+    Resolves the project's graph_index directory, reads the store type from
+    config, then replays the latest valid (or a specific) snapshot back into
+    the kuzu database.
+
+    Default (no flags): prints a summary of what WILL be restored and prompts
+    for confirmation.  Use --yes for CI/scripted invocations; --dry-run to
+    preview without touching the database.
+
+    The server MUST be stopped before running this command because kuzu does
+    not allow concurrent writers.
+    """
+    # --- Resolve state dir + store type ----------------------------------- #
+    project_root = resolve_project_root()
+    state_dir = project_root / STATE_DIR_NAME
+
+    block = _read_graphrag_block(state_dir)
+    store_type = str((block or {}).get("store_type") or "simple").lower()
+
+    if store_type != "kuzu":
+        console.print(
+            "[yellow]Graph restore only applies to the kuzu backend "
+            f"(configured store_type={store_type!r}). Nothing to do.[/yellow]"
+        )
+        return
+
+    # --- Guard: server must be stopped ------------------------------------ #
+    if _server_is_running(state_dir):
+        console.print(
+            "[red]Stop the server first (`agent-brain stop`) — restore "
+            "mutates the kuzu database the server holds open.[/red]"
+        )
+        raise SystemExit(1)
+
+    # --- Build the graph store manager ------------------------------------ #
+    graph_dir = _graph_index_dir(state_dir)
+    if GraphStoreManager is None:  # pragma: no cover
+        console.print(
+            "[red]Cannot import agent-brain-server. Install it with "
+            "`uv pip install agent-brain-rag`.[/red]"
+        )
+        raise SystemExit(1)
+
+    mgr = GraphStoreManager(graph_dir, "kuzu")
+
+    # --- Preview (plan) --------------------------------------------------- #
+    plan = mgr.plan_restore(snapshot_path)
+    if plan is None:
+        console.print(
+            "[yellow]No snapshot available to restore at "
+            f"{graph_dir / 'snapshots'}.[/yellow]"
+        )
+        raise SystemExit(1)
+
+    snap_file, triplet_count = plan
+    kuzu_db_path = graph_dir / "kuzu_db"
+    console.print(
+        f"Will restore [bold]{triplet_count}[/bold] triplets from "
+        f"[cyan]{snap_file.name}[/cyan] into [cyan]{kuzu_db_path}[/cyan]."
+    )
+
+    if dry_run:
+        console.print("(dry run — nothing changed)")
+        return
+
+    # --- Interactive confirmation ------------------------------------------ #
+    if not assume_yes:
+        confirmed = click.confirm("Proceed with restore?", default=False)
+        if not confirmed:
+            console.print("Aborted.")
+            return
+
+    # --- Execute restore --------------------------------------------------- #
+    restored = mgr.restore_from_snapshot(snapshot_path)
+    console.print(f"Restored [bold]{restored}[/bold] triplets.")

{agent_brain_cli-10.3.2 → agent_brain_cli-10.5.0}/agent_brain_cli/commands/install_agent.py

@@ -1,6 +1,8 @@
 """Install-agent command for installing runtime-specific plugin files."""
 
 import json
+import os
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -10,7 +12,12 @@ from rich.panel import Panel
 
 from agent_brain_cli.runtime.claude_converter import ClaudeConverter
 from agent_brain_cli.runtime.codex_converter import CodexConverter
-from agent_brain_cli.runtime.gemini_converter import GeminiConverter
+from agent_brain_cli.runtime.mcp_registration import (
+    McpRegistrationResult,
+    register_claude_mcp,
+    register_codex_mcp,
+    register_opencode_mcp,
+)
 from agent_brain_cli.runtime.opencode_converter import OpenCodeConverter
 from agent_brain_cli.runtime.parser import parse_plugin_dir
 from agent_brain_cli.runtime.skill_runtime_converter import SkillRuntimeConverter
@@ -28,10 +35,6 @@ INSTALL_DIRS: dict[str, dict[str, str]] = {
         "project": ".opencode/plugins/agent-brain",
         "global": "~/.config/opencode/plugins/agent-brain",
     },
-    "gemini": {
-        "project": ".gemini/plugins/agent-brain",
-        "global": "~/.config/gemini/plugins/agent-brain",
-    },
     "codex": {
         "project": ".codex/skills/agent-brain",
         "global": "~/.codex/skills/agent-brain",
@@ -42,17 +45,12 @@ INSTALL_DIRS: dict[str, dict[str, str]] = {
 DIR_REQUIRED_RUNTIMES = {"skill-runtime"}
 
 ConverterType = type[
-    ClaudeConverter
-    | OpenCodeConverter
-    | GeminiConverter
-    | SkillRuntimeConverter
-    | CodexConverter
+    ClaudeConverter | OpenCodeConverter | SkillRuntimeConverter | CodexConverter
 ]
 
 CONVERTERS: dict[str, ConverterType] = {
     "claude": ClaudeConverter,
     "opencode": OpenCodeConverter,
-    "gemini": GeminiConverter,
     "skill-runtime": SkillRuntimeConverter,
     "codex": CodexConverter,
 }
@@ -94,7 +92,89 @@ def _resolve_target_dir(
     return project_root / dir_template
 
 
-RUNTIME_CHOICES = ["claude", "opencode", "gemini", "skill-runtime", "codex"]
+RUNTIME_CHOICES = ["claude", "opencode", "skill-runtime", "codex"]
+
+# Runtimes for which we can auto-register the MCP server today, mapped to the
+# writer that knows that runtime's config schema. All writers share the
+# ``(config_path, state_dir, *, backend, auth, dry_run)`` signature.
+MCP_REGISTRARS: dict[str, Callable[..., McpRegistrationResult]] = {
+    "claude": register_claude_mcp,
+    "opencode": register_opencode_mcp,
+    "codex": register_codex_mcp,
+}
+
+
+def _codex_config_path() -> Path:
+    """Return Codex's MCP config file, honoring ``$CODEX_HOME``."""
+    codex_home = os.environ.get("CODEX_HOME")
+    base = Path(codex_home) if codex_home else Path.home() / ".codex"
+    return base / "config.toml"
+
+
+def _resolve_mcp_paths(
+    agent: str, scope: str, project_root: Path | None
+) -> tuple[Path, Path]:
+    """Return (config_path, state_dir) for MCP registration.
+
+    The config file follows each runtime's own discovery rules:
+
+    * **claude** — project ``.mcp.json`` at the root, global ``~/.claude.json``.
+    * **opencode** — project ``opencode.json`` at the root (highest-precedence
+      project config), global ``~/.config/opencode/opencode.json``.
+    * **codex** — always ``$CODEX_HOME/config.toml`` (default
+      ``~/.codex/config.toml``); Codex has no project-level MCP config, so the
+      file is shared and the project's ``.agent-brain`` is pinned via the entry.
+    """
+    root = project_root if project_root is not None else Path.cwd()
+    if agent == "opencode":
+        if scope == "global":
+            config = Path.home() / ".config" / "opencode" / "opencode.json"
+            return config, Path.home() / ".agent-brain"
+        return root / "opencode.json", root / ".agent-brain"
+    if agent == "codex":
+        state_dir = (
+            Path.home() / ".agent-brain" if scope == "global" else root / ".agent-brain"
+        )
+        return _codex_config_path(), state_dir
+    # claude (and any future mcpServers-style runtime)
+    if scope == "global":
+        return Path.home() / ".claude.json", Path.home() / ".agent-brain"
+    return root / ".mcp.json", root / ".agent-brain"
+
+
+def _register_mcp(
+    agent: str,
+    scope: str,
+    project_root: Path | None,
+    mcp_auth: str,
+    mcp_backend: str,
+    dry_run: bool,
+) -> dict[str, Any]:
+    """Register the MCP server for supported runtimes; report what happened."""
+    registrar = MCP_REGISTRARS.get(agent)
+    if registrar is None:
+        return {
+            "skipped": True,
+            "reason": (
+                f"MCP auto-registration is currently supported only for "
+                f"{', '.join(sorted(MCP_REGISTRARS))}; configure "
+                f"{agent} manually (see the configuring-agent-brain skill)."
+            ),
+        }
+    config_path, state_dir = _resolve_mcp_paths(agent, scope, project_root)
+    result = registrar(
+        config_path,
+        state_dir,
+        backend=mcp_backend,
+        auth=mcp_auth,
+        dry_run=dry_run,
+    )
+    return {
+        "skipped": False,
+        "action": result.action,
+        "path": str(result.path),
+        "server_name": result.server_name,
+    }
 
 
 @click.command("install-agent")
@@ -146,6 +226,23 @@ RUNTIME_CHOICES = ["claude", "opencode", "gemini", "skill-runtime", "codex"]
     type=click.Path(exists=True, file_okay=False, resolve_path=True),
     help="Project path for --project scope (default: cwd)",
 )
+@click.option(
+    "--with-mcp",
+    is_flag=True,
+    help="Also register the agent-brain MCP server (Claude Code, OpenCode, Codex)",
+)
+@click.option(
+    "--mcp-auth",
+    type=click.Choice(["none", "oauth"]),
+    default="none",
+    help="MCP client auth mode written into the registration (default: none)",
+)
+@click.option(
+    "--mcp-backend",
+    type=click.Choice(["auto", "uds", "http"]),
+    default="auto",
+    help="How the MCP server reaches agent-brain-serve (default: auto)",
+)
 def install_agent_command(
     agent: str,
     scope: str,
@@ -154,6 +251,9 @@ def install_agent_command(
     dry_run: bool,
     json_output: bool,
     path: str | None,
+    with_mcp: bool,
+    mcp_auth: str,
+    mcp_backend: str,
 ) -> None:
     """Install Agent Brain plugin for a specific runtime.
 
@@ -164,7 +264,7 @@ def install_agent_command(
     Examples:
       agent-brain install-agent --agent claude --project
       agent-brain install-agent --agent opencode --global
-      agent-brain install-agent --agent gemini --dry-run
+      agent-brain install-agent --agent claude --dry-run
       agent-brain install-agent --agent skill-runtime --dir ./my-skills
       agent-brain install-agent --agent codex
     """
@@ -220,6 +320,12 @@ def install_agent_command(
         converter = converter_cls()
         scope_enum = Scope.GLOBAL if scope == "global" else Scope.PROJECT
 
+        mcp_summary: dict[str, Any] | None = None
+        if with_mcp:
+            mcp_summary = _register_mcp(
+                agent, scope, project_root, mcp_auth, mcp_backend, dry_run
+            )
+
         if dry_run:
             _handle_dry_run(
                 converter,
@@ -229,6 +335,7 @@ def install_agent_command(
                 agent,
                 scope,
                 json_output,
+                mcp_summary,
             )
             return
 
@@ -250,6 +357,8 @@ def install_agent_command(
                 "files_created": len(files),
                 "source_dir": str(source),
             }
+            if mcp_summary is not None:
+                result["mcp_registration"] = mcp_summary
             click.echo(json.dumps(result, indent=2))
         else:
             console.print(
@@ -263,6 +372,7 @@ def install_agent_command(
                     border_style="green",
                 )
             )
+            _print_mcp_summary(mcp_summary)
 
     except SystemExit:
         raise
@@ -276,11 +386,7 @@ def install_agent_command(
 
 def _handle_dry_run(
     converter: (
-        ClaudeConverter
-        | OpenCodeConverter
-        | GeminiConverter
-        | SkillRuntimeConverter
-        | CodexConverter
+        ClaudeConverter | OpenCodeConverter | SkillRuntimeConverter | CodexConverter
     ),
     bundle: Any,
     target: Path,
@@ -288,18 +394,26 @@ def _handle_dry_run(
     agent: str,
     scope: str,
     json_output: bool,
+    mcp_summary: dict[str, Any] | None = None,
 ) -> None:
     """Handle dry-run mode: simulate install in temp dir."""
     import tempfile
 
     with tempfile.TemporaryDirectory() as tmp:
-        tmp_target = Path(tmp)
         # For Codex, pass tmp as project_root so AGENTS.md lands in tmpdir
         if isinstance(converter, CodexConverter):
+            tmp_target = Path(tmp)
             files = converter.install(
                 bundle, tmp_target, scope_enum, project_root=Path(tmp)
             )
         else:
+            # Mirror the real target's full structure under tmp so converters
+            # that write *outside* target_dir stay inside the sandbox — e.g.
+            # OpenCode writes opencode.json at target_dir.parent.parent, which
+            # escapes to an unwritable ancestor (CI: "/") if the temp target is
+            # shallow. Rooting at tmp + the target's relative path keeps every
+            # parent the converter computes inside the throwaway dir.
+            tmp_target = Path(tmp) / target.relative_to(target.anchor)
             files = converter.install(bundle, tmp_target, scope_enum)
         # Remap paths to real target
         planned: list[Path] = []
@@ -311,19 +425,17 @@ def _handle_dry_run(
                 planned.append(f)
 
     if json_output:
-        click.echo(
-            json.dumps(
-                {
-                    "dry_run": True,
-                    "agent": agent,
-                    "scope": scope,
-                    "target_dir": str(target),
-                    "files": [str(f) for f in planned],
-                    "file_count": len(planned),
-                },
-                indent=2,
-            )
-        )
+        payload: dict[str, Any] = {
+            "dry_run": True,
+            "agent": agent,
+            "scope": scope,
+            "target_dir": str(target),
+            "files": [str(f) for f in planned],
+            "file_count": len(planned),
+        }
+        if mcp_summary is not None:
+            payload["mcp_registration"] = mcp_summary
+        click.echo(json.dumps(payload, indent=2))
     else:
         console.print(
             Panel(
@@ -338,3 +450,17 @@ def _handle_dry_run(
         )
         for f in planned:
             console.print(f"  [dim]{f}[/]")
+        _print_mcp_summary(mcp_summary)
+
+
+def _print_mcp_summary(mcp_summary: dict[str, Any] | None) -> None:
+    """Render the MCP registration outcome for human-readable output."""
+    if mcp_summary is None:
+        return
+    if mcp_summary.get("skipped"):
+        console.print(f"[yellow]MCP:[/] {mcp_summary['reason']}")
+        return
+    console.print(
+        f"[green]MCP server registered[/] ([bold]{mcp_summary['action']}[/]) "
+        f"→ {mcp_summary['path']}"
+    )