cordis-bridge 0.1.1__tar.gz

cordis_bridge-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cordis Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cordis_bridge-0.1.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: cordis-bridge
+Version: 0.1.1
+Summary: CLI and optional MCP bridge for the Cordis cognitive runtime.
+Author: Cordis Contributors
+License: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cordis-core<0.2,>=0.1.1
+Requires-Dist: cordis-memory<0.2,>=0.1.1
+Requires-Dist: cordis-runtime<0.2,>=0.1.1
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.26; extra == "mcp"
+Dynamic: license-file
+
+# Cordis Bridge v0.1
+
+`cordis-bridge` exposes the existing CORDIS cognitive loop to a real host.
+It has no model, planner, HTTP server, or execution permission of its own.
+
+The bridge provides one shared Service behind two transports:
+
+- a JSON-only CLI for local hosts and scripts;
+- an optional stdio MCP server for agent hosts.
+
+```text
+host -> begin -> compact context + control signal
+host -> observe / check-action -> workflow evidence
+host -> finish -> Core feedback + Memory episode
+later host -> begin -> changed cognition
+```
+
+By default, durable state lives in `.cordis/` below the current directory:
+
+```text
+.cordis/state.json      Core learning state
+.cordis/cognition.db    Memory and relationship graph
+.cordis/focus.json      Active host-task focus for CLI/MCP process recovery
+```
+
+## CLI
+
+Every command reads one JSON object from a file or standard input and emits
+one JSON object. The input file defaults to `-` (standard input).
+
+```bat
+cordis begin task.json
+cordis query query.json
+cordis observe event.json
+cordis check-action action.json
+cordis finish feedback.json
+cordis status
+```
+
+Use `--data-dir PATH` before the command to keep a project-specific state
+directory elsewhere.
+
+## MCP
+
+Install the optional transport dependency and run:
+
+```bat
+pip install "cordis-bridge[mcp]"
+cordis-mcp --data-dir .cordis
+```
+
+The server exposes `cordis_begin`, `cordis_query`, `cordis_observe`,
+`cordis_check_action`, `cordis_finish`, and `cordis_status`. Each tool takes
+the same JSON contract as the matching CLI command.
+
+## Concurrency boundary
+
+CORDIS v0.1 assumes one mutating host per state directory. Run one MCP server
+per `.cordis` directory and keep CLI mutations for that directory sequential.
+The Core JSON state and Bridge focus snapshot are deliberately small local
+stores; multi-writer coordination is not part of this release.

cordis_bridge-0.1.1/README.md

@@ -0,0 +1,61 @@
+# Cordis Bridge v0.1
+
+`cordis-bridge` exposes the existing CORDIS cognitive loop to a real host.
+It has no model, planner, HTTP server, or execution permission of its own.
+
+The bridge provides one shared Service behind two transports:
+
+- a JSON-only CLI for local hosts and scripts;
+- an optional stdio MCP server for agent hosts.
+
+```text
+host -> begin -> compact context + control signal
+host -> observe / check-action -> workflow evidence
+host -> finish -> Core feedback + Memory episode
+later host -> begin -> changed cognition
+```
+
+By default, durable state lives in `.cordis/` below the current directory:
+
+```text
+.cordis/state.json      Core learning state
+.cordis/cognition.db    Memory and relationship graph
+.cordis/focus.json      Active host-task focus for CLI/MCP process recovery
+```
+
+## CLI
+
+Every command reads one JSON object from a file or standard input and emits
+one JSON object. The input file defaults to `-` (standard input).
+
+```bat
+cordis begin task.json
+cordis query query.json
+cordis observe event.json
+cordis check-action action.json
+cordis finish feedback.json
+cordis status
+```
+
+Use `--data-dir PATH` before the command to keep a project-specific state
+directory elsewhere.
+
+## MCP
+
+Install the optional transport dependency and run:
+
+```bat
+pip install "cordis-bridge[mcp]"
+cordis-mcp --data-dir .cordis
+```
+
+The server exposes `cordis_begin`, `cordis_query`, `cordis_observe`,
+`cordis_check_action`, `cordis_finish`, and `cordis_status`. Each tool takes
+the same JSON contract as the matching CLI command.
+
+## Concurrency boundary
+
+CORDIS v0.1 assumes one mutating host per state directory. Run one MCP server
+per `.cordis` directory and keep CLI mutations for that directory sequential.
+The Core JSON state and Bridge focus snapshot are deliberately small local
+stores; multi-writer coordination is not part of this release.

cordis_bridge-0.1.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cordis-bridge"
+version = "0.1.1"
+description = "CLI and optional MCP bridge for the Cordis cognitive runtime."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Cordis Contributors"}]
+dependencies = [
+  "cordis-core>=0.1.1,<0.2",
+  "cordis-memory>=0.1.1,<0.2",
+  "cordis-runtime>=0.1.1,<0.2",
+]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.26,<2"]
+
+[project.scripts]
+cordis = "cordis_bridge.cli:main"
+cordis-mcp = "cordis_bridge.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "../cordis-core/src", "../cordis-memory/src", "../cordis-runtime/src"]

cordis_bridge-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cordis_bridge-0.1.1/src/cordis_bridge/__init__.py

@@ -0,0 +1,7 @@
+"""Host transports for the model-agnostic CORDIS cognitive runtime."""
+
+from .service import BridgeValidationError, CordisService
+
+__version__ = "0.1.1"
+
+__all__ = ["BridgeValidationError", "CordisService", "__version__"]

cordis_bridge-0.1.1/src/cordis_bridge/cli.py

@@ -0,0 +1,105 @@
+"""JSON-only local command line transport for CORDIS."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from cordis_core import CordisValidationError
+from cordis_memory import MemoryValidationError
+from cordis_runtime import RuntimeValidationError
+
+from .service import BridgeValidationError, CordisService
+from .setup import SetupError, setup_claude_code, setup_codex, setup_hermes, setup_opencode
+
+
+USER_ERRORS = (BridgeValidationError, CordisValidationError, MemoryValidationError, RuntimeValidationError, SetupError)
+
+
+def _read_json(source: str) -> Mapping[str, Any]:
+    try:
+        raw = sys.stdin.read() if source == "-" else Path(source).read_text(encoding="utf-8")
+        value = json.loads(raw)
+    except (OSError, json.JSONDecodeError) as error:
+        raise BridgeValidationError(f"unable to read JSON input: {error}") from error
+    if not isinstance(value, dict):
+        raise BridgeValidationError("JSON input must be one object")
+    return value
+
+
+def _write_json(value: Mapping[str, Any]) -> None:
+    sys.stdout.write(json.dumps(value, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cordis", description="JSON bridge for the CORDIS cognitive runtime")
+    parser.add_argument("--data-dir", default=".cordis", help="directory containing CORDIS durable state")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("begin", "query", "observe", "check-action", "finish"):
+        command = sub.add_parser(name)
+        command.add_argument("input", nargs="?", default="-", help="JSON file path or - for standard input")
+    sub.add_parser("status")
+    sub.add_parser("init", help="initialize a local CORDIS state directory")
+    setup = sub.add_parser("setup", help="connect CORDIS to a supported host")
+    setup.add_argument("host", choices=("codex", "claude-code", "opencode", "hermes", "all"))
+    setup.add_argument("--config", help=argparse.SUPPRESS)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "setup":
+            setups = {
+                "codex": lambda: setup_codex(args.config),
+                "claude-code": setup_claude_code,
+                "opencode": lambda: setup_opencode(args.config),
+                "hermes": setup_hermes,
+            }
+            selected = tuple(setups) if args.host == "all" else (args.host,)
+            results = []
+            for host in selected:
+                result = setups[host]()
+                with CordisService(result["state_dir"]) as service:
+                    service.initialize()
+                result["initialized_data_dir"] = result["state_dir"]
+                results.append(result)
+            result = {"schema": "cordis.setup.v1", "hosts": results} if args.host == "all" else results[0]
+            _write_json(result)
+            return 0
+        with CordisService(args.data_dir) as service:
+            if args.command == "init":
+                service.initialize()
+                result = {
+                    "schema": "cordis.bridge.v1",
+                    "initialized": True,
+                    "data_dir": str(service.data_dir),
+                    "next": ["cordis status", "cordis-mcp --data-dir .cordis"],
+                }
+            elif args.command == "status":
+                result = service.status()
+            else:
+                request = _read_json(args.input)
+                commands: dict[str, Callable[[Mapping[str, Any]], dict[str, Any]]] = {
+                    "begin": service.begin,
+                    "query": service.query,
+                    "observe": service.observe,
+                    "check-action": service.check_action,
+                    "finish": service.finish,
+                }
+                result = commands[args.command](request)
+        _write_json(result)
+        return 0
+    except USER_ERRORS as error:
+        _write_json({"error": {"type": "validation_error", "message": str(error)}})
+        return 2
+    except Exception as error:  # Keep the machine-readable contract even for host failures.
+        _write_json({"error": {"type": "internal_error", "message": str(error)}})
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cordis_bridge-0.1.1/src/cordis_bridge/mcp_server.py

@@ -0,0 +1,79 @@
+"""Optional FastMCP transport; importing this module does not require MCP."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any, Mapping
+
+from .service import CordisService
+
+
+class McpUnavailableError(RuntimeError):
+    """Raised only when the optional ``mcp`` dependency is absent."""
+
+
+def create_server(data_dir: str | Path | None = None) -> Any:
+    """Build a stdio MCP server around one persistent Bridge service."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as error:
+        raise McpUnavailableError("MCP support requires: pip install 'cordis-bridge[mcp]'") from error
+
+    service = CordisService(data_dir)
+    server = FastMCP(
+        "CORDIS",
+        instructions=(
+            "CORDIS is a model-agnostic cognitive runtime. Call cordis_begin before work, "
+            "record meaningful events, then call cordis_finish with observable evidence."
+        ),
+    )
+
+    @server.tool(name="cordis_begin", description="Start a structured CORDIS task and receive compact cognitive context.")
+    def cordis_begin(payload: dict[str, Any]) -> dict[str, Any]:
+        return service.begin(payload)
+
+    @server.tool(name="cordis_query", description="Retrieve novel project-safe cognition for an active CORDIS task.")
+    def cordis_query(payload: dict[str, Any]) -> dict[str, Any]:
+        return service.query(payload)
+
+    @server.tool(name="cordis_observe", description="Record a plan, tool, test, artifact, or error event for an active task.")
+    def cordis_observe(payload: dict[str, Any]) -> dict[str, Any]:
+        return service.observe(payload)
+
+    @server.tool(name="cordis_check_action", description="Return a deterministic attention-drift and destructive-action signal.")
+    def cordis_check_action(payload: dict[str, Any]) -> dict[str, Any]:
+        return service.check_action(payload)
+
+    @server.tool(name="cordis_finish", description="Finalize a task with outcome, evidence, attribution, and optional lesson.")
+    def cordis_finish(payload: dict[str, Any]) -> dict[str, Any]:
+        return service.finish(payload)
+
+    @server.tool(name="cordis_status", description="Return observable Core, Memory, and active-task state.")
+    def cordis_status() -> dict[str, Any]:
+        return service.status()
+
+    # Keep ownership explicit for embedding hosts and Bridge tests. FastMCP
+    # itself does not manage application resources constructed outside a
+    # lifespan callback.
+    setattr(server, "cordis_service", service)
+    return server
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cordis-mcp", description="Run CORDIS as a stdio MCP server")
+    parser.add_argument("--data-dir", default=".cordis", help="directory containing CORDIS durable state")
+    args = parser.parse_args(argv)
+    try:
+        server = create_server(args.data_dir)
+    except McpUnavailableError as error:
+        parser.error(str(error))
+    try:
+        server.run(transport="stdio")
+    finally:
+        server.cordis_service.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cordis_bridge-0.1.1/src/cordis_bridge/service.py

@@ -0,0 +1,165 @@
+"""Persistent host service shared by the CORDIS CLI and MCP transports."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Iterable, Mapping
+
+from cordis_core import CordisRuntime
+from cordis_memory import CognitiveStore
+from cordis_runtime import CordisHostRuntime
+
+
+BRIDGE_SCHEMA = "cordis.bridge.v1"
+
+
+class BridgeValidationError(ValueError):
+    """Raised when a transport breaks the small Bridge request contract."""
+
+
+def _object(value: Any, field: str = "payload") -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise BridgeValidationError(f"{field} must be an object")
+    return value
+
+
+def _text(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise BridgeValidationError(f"{field} must be a non-empty string")
+    return value.strip()
+
+
+def _string_list(value: Any, field: str) -> tuple[str, ...] | None:
+    if value is None:
+        return None
+    if not isinstance(value, list) or any(not isinstance(item, str) or not item.strip() for item in value):
+        raise BridgeValidationError(f"{field} must be a list of non-empty strings")
+    return tuple(item.strip() for item in value)
+
+
+class CordisService:
+    """Persist host focus around the existing Core, Memory, and Runtime APIs.
+
+    Core owns learning state in ``state.json`` and Memory owns graph state in
+    ``cognition.db``.  The tiny ``focus.json`` file exists only because CLI
+    and MCP calls can arrive in separate processes while Runtime focus is
+    intentionally task-local and in-memory.
+    """
+
+    def __init__(self, data_dir: str | Path | None = None):
+        self.data_dir = Path(data_dir or ".cordis").resolve()
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.focus_path = self.data_dir / "focus.json"
+        self.core = CordisRuntime(self.data_dir / "state.json")
+        self.memory = CognitiveStore(self.data_dir / "cognition.db")
+        self.runtime = CordisHostRuntime(self.core, self.memory)
+        self._closed = False
+        self._restore_focus()
+
+    def close(self) -> None:
+        if not self._closed:
+            self.memory.close()
+            self._closed = True
+
+    def __enter__(self) -> "CordisService":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _restore_focus(self) -> None:
+        if not self.focus_path.exists():
+            return
+        try:
+            raw = json.loads(self.focus_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise BridgeValidationError("focus.json is unreadable; remove it only after resolving active tasks") from error
+        if not isinstance(raw, dict) or raw.get("schema") != BRIDGE_SCHEMA or not isinstance(raw.get("tasks"), dict):
+            raise BridgeValidationError("focus.json has an unsupported schema")
+        tasks = raw["tasks"]
+        if any(not isinstance(task_id, str) or not isinstance(focus, dict) for task_id, focus in tasks.items()):
+            raise BridgeValidationError("focus.json contains invalid task focus")
+        self.runtime.restore_focus(tasks)
+
+    def _save_focus(self) -> None:
+        payload = {
+            "schema": BRIDGE_SCHEMA,
+            "tasks": self.runtime.export_focus(),
+        }
+        handle = tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=self.data_dir, prefix="focus-", suffix=".tmp", delete=False
+        )
+        try:
+            json.dump(payload, handle, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+            handle.flush()
+            os.fsync(handle.fileno())
+            handle.close()
+            os.replace(handle.name, self.focus_path)
+        finally:
+            if not handle.closed:
+                handle.close()
+            if os.path.exists(handle.name):
+                os.unlink(handle.name)
+
+    def initialize(self) -> None:
+        """Materialize the three durable stores without inventing experience."""
+        self.core.initialize()
+        self._save_focus()
+
+    @staticmethod
+    def _result(value: Mapping[str, Any]) -> Dict[str, Any]:
+        return {"schema": BRIDGE_SCHEMA, "result": dict(value)}
+
+    def begin(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        result = self.runtime.begin(_object(payload))
+        self._save_focus()
+        return self._result(result)
+
+    def query(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        request = _object(payload)
+        task_id = _text(request.get("task_id"), "task_id")
+        intent = _text(request.get("intent"), "intent")
+        scopes = _string_list(request.get("scopes"), "scopes")
+        kinds = _string_list(request.get("kinds"), "kinds")
+        limit = request.get("limit", 3)
+        if not isinstance(limit, int):
+            raise BridgeValidationError("limit must be an integer")
+        kwargs: Dict[str, Any] = {"intent": intent, "limit": limit}
+        if scopes is not None:
+            kwargs["scopes"] = scopes
+        if kinds is not None:
+            kwargs["kinds"] = kinds
+        result = self.runtime.query(task_id, **kwargs)
+        self._save_focus()
+        return self._result(result)
+
+    def observe(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        request = _object(payload)
+        result = self.runtime.observe(
+            _text(request.get("task_id"), "task_id"), _object(request.get("event"), "event")
+        )
+        return self._result(result)
+
+    def check_action(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        request = _object(payload)
+        result = self.runtime.check_action(
+            _text(request.get("task_id"), "task_id"), _object(request.get("action"), "action")
+        )
+        return self._result(result)
+
+    def finish(self, payload: Mapping[str, Any]) -> Dict[str, Any]:
+        result = self.runtime.finish(_object(payload))
+        self._save_focus()
+        return self._result(result)
+
+    def status(self) -> Dict[str, Any]:
+        return {
+            "schema": BRIDGE_SCHEMA,
+            "data_dir": str(self.data_dir),
+            "active_task_count": len(self.runtime.export_focus()),
+            "core": self.core.status(),
+            "memory": self.memory.status(),
+        }

cordis_bridge-0.1.1/src/cordis_bridge/setup.py

@@ -0,0 +1,274 @@
+"""Explicit host setup helpers for CORDIS."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+
+BEGIN_MARKER = "# BEGIN CORDIS MANAGED MCP"
+END_MARKER = "# END CORDIS MANAGED MCP"
+PROTOCOL_BEGIN = "<!-- BEGIN CORDIS MANAGED PROTOCOL -->"
+PROTOCOL_END = "<!-- END CORDIS MANAGED PROTOCOL -->"
+PROTOCOL = """<!-- BEGIN CORDIS MANAGED PROTOCOL -->
+## CORDIS cognitive loop
+
+Use the CORDIS MCP tools for substantive tasks that can produce observable work or reusable learning.
+
+1. Call `cordis_begin` before substantive work and follow the returned cognitive context and control signal.
+2. Call `cordis_observe` only for meaningful plans, tool results, tests, artifacts, or errors; do not log routine chatter.
+3. Call `cordis_check_action` before destructive or potentially drifting actions.
+4. Call `cordis_finish` exactly once with observable evidence and an honest outcome before declaring the task complete.
+5. Skip the loop for greetings, casual conversation, and trivial read-only questions.
+<!-- END CORDIS MANAGED PROTOCOL -->"""
+
+
+class SetupError(ValueError):
+    """Raised when automatic host configuration would be unsafe."""
+
+
+def _toml_string(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def codex_config_path() -> Path:
+    root = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+    return root / "config.toml"
+
+
+def host_state_dir(host: str) -> Path:
+    return (Path.home() / ".cordis" / "hosts" / host).resolve()
+
+
+def _server_command(state_dir: Path) -> list[str]:
+    return [sys.executable, "-m", "cordis_bridge.mcp_server", "--data-dir", str(state_dir)]
+
+
+def _host_executable(name: str) -> str:
+    candidates = [name]
+    if os.name == "nt":
+        candidates = [f"{name}.exe", f"{name}.cmd", f"{name}.bat", name]
+    for candidate in candidates:
+        found = shutil.which(candidate)
+        if found and not found.lower().endswith(".ps1"):
+            return found
+    raise SetupError(f"{name} is not installed or is not available on PATH")
+
+
+def _run(command: list[str], *, input_text: str | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        input=input_text,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+
+
+def _install_protocol(path: Path) -> tuple[bool, str | None]:
+    path = path.expanduser().resolve()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    original = path.read_text(encoding="utf-8") if path.exists() else ""
+    if PROTOCOL_BEGIN in original:
+        start = original.index(PROTOCOL_BEGIN)
+        end_marker = original.find(PROTOCOL_END, start)
+        if end_marker < 0:
+            raise SetupError(f"{path} contains an incomplete CORDIS protocol block")
+        end = end_marker + len(PROTOCOL_END)
+        updated = original[:start] + PROTOCOL + original[end:]
+    else:
+        separator = "" if not original else ("\n" if original.endswith("\n") else "\n\n")
+        updated = original + separator + PROTOCOL + "\n"
+    changed = updated != original
+    backup = None
+    if changed and path.exists():
+        backup_path = path.with_suffix(path.suffix + ".cordis-backup")
+        shutil.copy2(path, backup_path)
+        backup = str(backup_path)
+    if changed:
+        path.write_text(updated, encoding="utf-8")
+    return changed, backup
+
+
+def _protocol_path(host: str) -> Path:
+    if host == "codex":
+        root = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+        override = root / "AGENTS.override.md"
+        return override if override.exists() else root / "AGENTS.md"
+    if host == "claude-code":
+        return Path.home() / ".claude" / "CLAUDE.md"
+    if host == "opencode":
+        return Path.home() / ".config" / "opencode" / "AGENTS.md"
+    if host == "hermes":
+        return Path.home() / ".hermes" / "AGENTS.md"
+    raise SetupError(f"unsupported host: {host}")
+
+
+def _with_protocol(result: Dict[str, Any]) -> Dict[str, Any]:
+    path = _protocol_path(result["host"])
+    changed, backup = _install_protocol(path)
+    result["protocol_path"] = str(path.resolve())
+    result["protocol_changed"] = changed
+    result["protocol_backup_path"] = backup
+    return result
+
+
+def _result(host: str, state_dir: Path, **values: Any) -> Dict[str, Any]:
+    return {
+        "host": host,
+        "configured": True,
+        "state_dir": str(state_dir),
+        "state_policy": "one writer-safe state directory per host; projects remain isolated by project_id",
+        **values,
+    }
+
+
+def setup_codex(config_path: str | Path | None = None, state_dir: str | Path | None = None) -> Dict[str, Any]:
+    """Install a managed stdio MCP block in the user's Codex config."""
+    path = Path(config_path) if config_path is not None else codex_config_path()
+    path = path.expanduser().resolve()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    original = path.read_text(encoding="utf-8") if path.exists() else ""
+    state = Path(state_dir).expanduser().resolve() if state_dir else host_state_dir("codex")
+
+    if "[mcp_servers.cordis]" in original and BEGIN_MARKER not in original:
+        raise SetupError(
+            f"{path} already contains an unmanaged [mcp_servers.cordis] section; "
+            "remove or rename it before running setup"
+        )
+
+    block = "\n".join(
+        (
+            BEGIN_MARKER,
+            "[mcp_servers.cordis]",
+            f"command = {_toml_string(sys.executable)}",
+            f"args = [\"-m\", \"cordis_bridge.mcp_server\", \"--data-dir\", {_toml_string(str(state))}]",
+            "startup_timeout_sec = 30",
+            END_MARKER,
+        )
+    )
+
+    if BEGIN_MARKER in original:
+        start = original.index(BEGIN_MARKER)
+        end_marker = original.find(END_MARKER, start)
+        if end_marker < 0:
+            raise SetupError(f"{path} contains an incomplete CORDIS managed block")
+        end = end_marker + len(END_MARKER)
+        updated = original[:start] + block + original[end:]
+    else:
+        separator = "" if not original else ("\n" if original.endswith("\n") else "\n\n")
+        updated = original + separator + block + "\n"
+
+    changed = updated != original
+    backup = None
+    if changed and path.exists():
+        backup = path.with_suffix(path.suffix + ".cordis-backup")
+        shutil.copy2(path, backup)
+    if changed:
+        path.write_text(updated, encoding="utf-8")
+
+    return _with_protocol(_result(
+        "codex",
+        state,
+        changed=changed,
+        config_path=str(path),
+        backup_path=str(backup) if backup else None,
+        restart_required=True,
+    ))
+
+
+def setup_claude_code(state_dir: str | Path | None = None) -> Dict[str, Any]:
+    state = Path(state_dir).expanduser().resolve() if state_dir else host_state_dir("claude-code")
+    executable = _host_executable("claude")
+    existing = _run([executable, "mcp", "get", "cordis"])
+    if existing.returncode == 0:
+        if str(state) not in existing.stdout or sys.executable not in existing.stdout:
+            raise SetupError("Claude Code already has a different MCP server named cordis")
+        return _with_protocol(_result("claude-code", state, changed=False, verified=True, restart_required=True))
+    command = [executable, "mcp", "add", "--scope", "user", "cordis", "--", *_server_command(state)]
+    added = _run(command)
+    if added.returncode != 0:
+        raise SetupError(f"Claude Code rejected CORDIS MCP setup: {(added.stderr or added.stdout).strip()}")
+    verified = _run([executable, "mcp", "get", "cordis"])
+    if verified.returncode != 0:
+        raise SetupError("Claude Code saved CORDIS but could not verify the server")
+    return _with_protocol(_result("claude-code", state, changed=True, verified=True, restart_required=True))
+
+
+def setup_hermes(state_dir: str | Path | None = None) -> Dict[str, Any]:
+    state = Path(state_dir).expanduser().resolve() if state_dir else host_state_dir("hermes")
+    executable = _host_executable("hermes")
+    existing = _run([executable, "mcp", "test", "cordis"])
+    if existing.returncode == 0 and "Connected" in existing.stdout:
+        return _with_protocol(_result("hermes", state, changed=False, verified=True, restart_required=True))
+    command = [
+        executable,
+        "mcp",
+        "add",
+        "cordis",
+        "--command",
+        sys.executable,
+        "--args",
+        "-m",
+        "cordis_bridge.mcp_server",
+        "--data-dir",
+        str(state),
+    ]
+    added = _run(command, input_text="y\n")
+    if added.returncode != 0 or "Saved 'cordis'" not in added.stdout:
+        raise SetupError(f"Hermes rejected CORDIS MCP setup: {(added.stderr or added.stdout).strip()}")
+    verified = _run([executable, "mcp", "test", "cordis"])
+    if verified.returncode != 0:
+        raise SetupError(f"Hermes saved CORDIS but connection verification failed: {verified.stdout.strip()}")
+    return _with_protocol(_result("hermes", state, changed=True, verified=True, restart_required=True))
+
+
+def opencode_config_path() -> Path:
+    return (Path.home() / ".config" / "opencode" / "opencode.json").resolve()
+
+
+def setup_opencode(
+    config_path: str | Path | None = None, state_dir: str | Path | None = None
+) -> Dict[str, Any]:
+    path = Path(config_path).expanduser().resolve() if config_path else opencode_config_path()
+    state = Path(state_dir).expanduser().resolve() if state_dir else host_state_dir("opencode")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    original_text = path.read_text(encoding="utf-8") if path.exists() else ""
+    try:
+        config = json.loads(original_text) if original_text else {"$schema": "https://opencode.ai/config.json"}
+    except json.JSONDecodeError as error:
+        raise SetupError(f"{path} is not strict JSON; CORDIS will not rewrite JSONC automatically") from error
+    if not isinstance(config, dict):
+        raise SetupError(f"{path} must contain one JSON object")
+    mcp = config.setdefault("mcp", {})
+    if not isinstance(mcp, dict):
+        raise SetupError(f"{path} field 'mcp' must be an object")
+    desired = {"type": "local", "command": _server_command(state), "enabled": True, "timeout": 30000}
+    existing = mcp.get("cordis")
+    if existing is not None and existing != desired:
+        raise SetupError(f"{path} already contains a different mcp.cordis configuration")
+    mcp["cordis"] = desired
+    updated = json.dumps(config, ensure_ascii=False, indent=2) + "\n"
+    changed = updated != original_text
+    backup = None
+    if changed and path.exists():
+        backup = path.with_suffix(path.suffix + ".cordis-backup")
+        shutil.copy2(path, backup)
+    if changed:
+        path.write_text(updated, encoding="utf-8")
+    return _with_protocol(_result(
+        "opencode",
+        state,
+        changed=changed,
+        verified=True,
+        config_path=str(path),
+        backup_path=str(backup) if backup else None,
+        restart_required=True,
+    ))

cordis_bridge-0.1.1/src/cordis_bridge.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: cordis-bridge
+Version: 0.1.1
+Summary: CLI and optional MCP bridge for the Cordis cognitive runtime.
+Author: Cordis Contributors
+License: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cordis-core<0.2,>=0.1.1
+Requires-Dist: cordis-memory<0.2,>=0.1.1
+Requires-Dist: cordis-runtime<0.2,>=0.1.1
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.26; extra == "mcp"
+Dynamic: license-file
+
+# Cordis Bridge v0.1
+
+`cordis-bridge` exposes the existing CORDIS cognitive loop to a real host.
+It has no model, planner, HTTP server, or execution permission of its own.
+
+The bridge provides one shared Service behind two transports:
+
+- a JSON-only CLI for local hosts and scripts;
+- an optional stdio MCP server for agent hosts.
+
+```text
+host -> begin -> compact context + control signal
+host -> observe / check-action -> workflow evidence
+host -> finish -> Core feedback + Memory episode
+later host -> begin -> changed cognition
+```
+
+By default, durable state lives in `.cordis/` below the current directory:
+
+```text
+.cordis/state.json      Core learning state
+.cordis/cognition.db    Memory and relationship graph
+.cordis/focus.json      Active host-task focus for CLI/MCP process recovery
+```
+
+## CLI
+
+Every command reads one JSON object from a file or standard input and emits
+one JSON object. The input file defaults to `-` (standard input).
+
+```bat
+cordis begin task.json
+cordis query query.json
+cordis observe event.json
+cordis check-action action.json
+cordis finish feedback.json
+cordis status
+```
+
+Use `--data-dir PATH` before the command to keep a project-specific state
+directory elsewhere.
+
+## MCP
+
+Install the optional transport dependency and run:
+
+```bat
+pip install "cordis-bridge[mcp]"
+cordis-mcp --data-dir .cordis
+```
+
+The server exposes `cordis_begin`, `cordis_query`, `cordis_observe`,
+`cordis_check_action`, `cordis_finish`, and `cordis_status`. Each tool takes
+the same JSON contract as the matching CLI command.
+
+## Concurrency boundary
+
+CORDIS v0.1 assumes one mutating host per state directory. Run one MCP server
+per `.cordis` directory and keep CLI mutations for that directory sequential.
+The Core JSON state and Bridge focus snapshot are deliberately small local
+stores; multi-writer coordination is not part of this release.

cordis_bridge-0.1.1/src/cordis_bridge.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/cordis_bridge/__init__.py
+src/cordis_bridge/cli.py
+src/cordis_bridge/mcp_server.py
+src/cordis_bridge/service.py
+src/cordis_bridge/setup.py
+src/cordis_bridge.egg-info/PKG-INFO
+src/cordis_bridge.egg-info/SOURCES.txt
+src/cordis_bridge.egg-info/dependency_links.txt
+src/cordis_bridge.egg-info/entry_points.txt
+src/cordis_bridge.egg-info/requires.txt
+src/cordis_bridge.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_mcp.py
+tests/test_service.py
+tests/test_setup.py

cordis_bridge-0.1.1/src/cordis_bridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cordis_bridge-0.1.1/src/cordis_bridge.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cordis = cordis_bridge.cli:main
+cordis-mcp = cordis_bridge.mcp_server:main

cordis_bridge-0.1.1/src/cordis_bridge.egg-info/requires.txt

@@ -0,0 +1,6 @@
+cordis-core<0.2,>=0.1.1
+cordis-memory<0.2,>=0.1.1
+cordis-runtime<0.2,>=0.1.1
+
+[mcp]
+mcp<2,>=1.26

cordis_bridge-0.1.1/src/cordis_bridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+cordis_bridge

cordis_bridge-0.1.1/tests/test_cli.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+class CordisCliTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tempdir = tempfile.TemporaryDirectory()
+        self.data_dir = Path(self.tempdir.name) / ".cordis"
+        self.env = dict(os.environ)
+        source_paths = [
+            str(ROOT / "cordis-bridge" / "src"),
+            str(ROOT / "cordis-runtime" / "src"),
+            str(ROOT / "cordis-memory" / "src"),
+            str(ROOT / "cordis-core" / "src"),
+        ]
+        self.env["PYTHONPATH"] = os.pathsep.join(source_paths + [self.env.get("PYTHONPATH", "")])
+
+    def tearDown(self) -> None:
+        self.tempdir.cleanup()
+
+    def call(self, command: str, payload: dict | None = None) -> tuple[int, dict]:
+        args = [sys.executable, "-m", "cordis_bridge.cli", "--data-dir", str(self.data_dir), command]
+        completed = subprocess.run(
+            args,
+            input=json.dumps(payload) if payload is not None else None,
+            text=True,
+            capture_output=True,
+            env=self.env,
+            check=False,
+        )
+        return completed.returncode, json.loads(completed.stdout)
+
+    @staticmethod
+    def task() -> dict:
+        return {
+            "task": {
+                "goal": "Start an HTTP adapter in a clean environment",
+                "domain": "software",
+                "project_id": "cli-test",
+                "strategy_id": "import_runtime_dependencies",
+                "stakes": "medium",
+            },
+            "complexity": 0.4,
+            "acceptance_evidence": ["clean-environment test passes"],
+        }
+
+    def test_cli_closes_the_learning_loop_across_processes(self) -> None:
+        code, first = self.call("begin", self.task())
+        self.assertEqual(code, 0)
+        task_id = first["result"]["task_id"]
+
+        code, finished = self.call(
+            "finish",
+            {
+                "task_id": task_id,
+                "outcome": "failure",
+                "attribution": "strategy",
+                "lesson": "Avoid import-time runtime initialization in reusable modules.",
+                "evidence": [{"kind": "strategy", "passed": False, "summary": "clean import failed"}],
+            },
+        )
+        self.assertEqual(code, 0)
+        self.assertIn("strategy_outcome", finished["result"]["learning"]["state_updates"])
+
+        code, second = self.call("begin", self.task())
+        self.assertEqual(code, 0)
+        self.assertEqual(second["result"]["cognitive_ir"]["strategy"]["status"], "avoid_until_revalidated")
+
+    def test_cli_init_materializes_three_local_state_stores(self) -> None:
+        code, result = self.call("init")
+        self.assertEqual(code, 0)
+        self.assertTrue(result["initialized"])
+        self.assertEqual(result["data_dir"], str(self.data_dir.resolve()))
+        self.assertTrue((self.data_dir / "state.json").is_file())
+        self.assertTrue((self.data_dir / "cognition.db").is_file())
+        self.assertTrue((self.data_dir / "focus.json").is_file())
+
+    def test_cli_uses_json_error_contract(self) -> None:
+        code, result = self.call("finish", {"task_id": "missing", "outcome": "failure", "evidence": []})
+        self.assertEqual(code, 2)
+        self.assertEqual(result["error"]["type"], "validation_error")

cordis_bridge-0.1.1/tests/test_mcp.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import importlib.util
+import asyncio
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+if importlib.util.find_spec("mcp"):
+    from mcp import ClientSession
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+else:  # Keep the source suite usable without the optional transport dependency.
+    ClientSession = StdioServerParameters = stdio_client = None
+
+from cordis_bridge.mcp_server import create_server
+
+
+@unittest.skipUnless(importlib.util.find_spec("mcp"), "optional mcp package is not installed")
+class CordisMcpTests(unittest.TestCase):
+    def test_server_registers_the_six_bridge_tools(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            server = create_server(directory)
+            try:
+                names = {tool.name for tool in asyncio.run(server.list_tools())}
+            finally:
+                server.cordis_service.close()
+        self.assertEqual(
+            names,
+            {
+                "cordis_begin",
+                "cordis_query",
+                "cordis_observe",
+                "cordis_check_action",
+                "cordis_finish",
+                "cordis_status",
+            },
+        )
+
+
+@unittest.skipUnless(importlib.util.find_spec("mcp"), "optional mcp package is not installed")
+class CordisMcpStdioTests(unittest.IsolatedAsyncioTestCase):
+    async def test_stdio_server_handles_a_real_begin_request(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            parameters = StdioServerParameters(
+                command=sys.executable,
+                args=["-m", "cordis_bridge.mcp_server", "--data-dir", str(Path(directory) / "state")],
+            )
+            async with stdio_client(parameters) as (read, write):
+                async with ClientSession(read, write) as session:
+                    await session.initialize()
+                    listed = await session.list_tools()
+                    self.assertIn("cordis_begin", {tool.name for tool in listed.tools})
+                    result = await session.call_tool(
+                        "cordis_begin",
+                        {
+                            "payload": {
+                                "task": {
+                                    "goal": "Verify the MCP transport",
+                                    "domain": "software",
+                                    "project_id": "mcp-test",
+                                    "strategy_id": "inspect",
+                                    "stakes": "low",
+                                },
+                                "complexity": 0.1,
+                                "acceptance_evidence": ["MCP response is returned"],
+                            }
+                        },
+                    )
+        self.assertFalse(result.isError)
+        self.assertIn("cordis.runtime.v1", result.content[0].text)

cordis_bridge-0.1.1/tests/test_service.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from cordis_bridge import CordisService
+
+
+class CordisServiceTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tempdir = tempfile.TemporaryDirectory()
+        self.data_dir = Path(self.tempdir.name) / ".cordis"
+
+    def tearDown(self) -> None:
+        self.tempdir.cleanup()
+
+    @staticmethod
+    def task() -> dict:
+        return {
+            "task": {
+                "goal": "Inspect the login integration test logs",
+                "domain": "software",
+                "project_id": "bridge-test",
+                "strategy_id": "inspect_logs",
+                "stakes": "medium",
+            },
+            "complexity": 0.4,
+            "current_step": "Inspect the failing integration test",
+            "constraints": ["Do not change the database schema"],
+            "acceptance_evidence": ["login integration test passes"],
+        }
+
+    def test_service_persists_active_focus_for_a_new_process(self) -> None:
+        with CordisService(self.data_dir) as first:
+            begin = first.begin(self.task())
+        task_id = begin["result"]["task_id"]
+
+        with CordisService(self.data_dir) as second:
+            action = second.check_action(
+                {
+                    "task_id": task_id,
+                    "action": {"description": "Inspect login logs", "purpose": "Find test failure"},
+                }
+            )
+            self.assertTrue(action["result"]["aligned"])
+            second.observe(
+                {
+                    "task_id": task_id,
+                    "event": {
+                        "event_type": "tool_failed",
+                        "tool": "shell",
+                        "subject": "integration test",
+                        "expected": "tests pass",
+                        "actual": "exit code 1",
+                        "error_class": "test_failure",
+                    },
+                }
+            )
+            second.finish(
+                {
+                    "task_id": task_id,
+                    "outcome": "failure",
+                    "attribution": "strategy",
+                    "lesson": "Inspect configuration before relying only on logs.",
+                    "evidence": [{"kind": "strategy", "passed": False, "summary": "log-only approach failed"}],
+                }
+            )
+
+        with CordisService(self.data_dir) as third:
+            changed = third.begin(self.task())
+            context = changed["result"]
+            self.assertEqual(context["cognitive_ir"]["strategy"]["status"], "avoid_until_revalidated")
+            self.assertEqual(context["control"]["mode"], "high_intervention")
+            self.assertIn("repeat_failed_strategy:inspect_logs", context["model_context"])
+            self.assertEqual(third.status()["active_task_count"], 1)
+
+    def test_status_combines_core_memory_and_active_tasks(self) -> None:
+        with CordisService(self.data_dir) as service:
+            service.begin(self.task())
+            status = service.status()
+        self.assertEqual(status["schema"], "cordis.bridge.v1")
+        self.assertEqual(status["active_task_count"], 1)
+        self.assertEqual(status["core"]["task_count"], 1)
+        self.assertIn("memory_counts", status["memory"])

cordis_bridge-0.1.1/tests/test_setup.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from cordis_bridge.setup import (
+    BEGIN_MARKER,
+    PROTOCOL_BEGIN,
+    SetupError,
+    setup_claude_code,
+    setup_codex,
+    setup_hermes,
+    setup_opencode,
+)
+
+
+class CordisCodexSetupTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tempdir = tempfile.TemporaryDirectory()
+        self.config = Path(self.tempdir.name) / "config.toml"
+
+    def tearDown(self) -> None:
+        self.tempdir.cleanup()
+
+    def test_setup_adds_managed_block_and_preserves_existing_config(self) -> None:
+        self.config.write_text('model = "example"\n', encoding="utf-8")
+        with patch("cordis_bridge.setup.sys.executable", r"C:\Cordis\python.exe"):
+            result = setup_codex(self.config, Path(self.tempdir.name) / "state")
+        content = self.config.read_text(encoding="utf-8")
+        self.assertIn('model = "example"', content)
+        self.assertIn(BEGIN_MARKER, content)
+        self.assertIn('[mcp_servers.cordis]', content)
+        self.assertIn('command = "C:\\\\Cordis\\\\python.exe"', content)
+        self.assertTrue(result["changed"])
+        self.assertTrue(Path(result["backup_path"]).is_file())
+
+    def test_setup_is_idempotent(self) -> None:
+        first = setup_codex(self.config)
+        second = setup_codex(self.config)
+        self.assertTrue(first["changed"])
+        self.assertFalse(second["changed"])
+        self.assertEqual(self.config.read_text(encoding="utf-8").count(BEGIN_MARKER), 1)
+
+    def test_setup_refuses_unmanaged_existing_server(self) -> None:
+        self.config.write_text("[mcp_servers.cordis]\ncommand = 'custom'\n", encoding="utf-8")
+        with self.assertRaises(SetupError):
+            setup_codex(self.config)
+
+    @patch("cordis_bridge.setup._protocol_path")
+    def test_setup_installs_managed_usage_protocol(self, protocol_path) -> None:
+        protocol = Path(self.tempdir.name) / "AGENTS.md"
+        protocol_path.return_value = protocol
+        setup_codex(self.config, Path(self.tempdir.name) / "state")
+        first = protocol.read_text(encoding="utf-8")
+        self.assertIn(PROTOCOL_BEGIN, first)
+        self.assertIn("cordis_begin", first)
+        setup_codex(self.config, Path(self.tempdir.name) / "state")
+        self.assertEqual(protocol.read_text(encoding="utf-8").count(PROTOCOL_BEGIN), 1)
+
+    def test_opencode_setup_merges_official_local_mcp_schema(self) -> None:
+        self.config.write_text('{"model": "example"}\n', encoding="utf-8")
+        state = Path(self.tempdir.name) / "opencode-state"
+        with patch("cordis_bridge.setup._protocol_path", return_value=Path(self.tempdir.name) / "AGENTS.md"):
+            result = setup_opencode(self.config, state)
+        value = __import__("json").loads(self.config.read_text(encoding="utf-8"))
+        self.assertEqual(value["model"], "example")
+        self.assertEqual(value["mcp"]["cordis"]["type"], "local")
+        self.assertEqual(value["mcp"]["cordis"]["command"][-1], str(state.resolve()))
+        self.assertTrue(value["mcp"]["cordis"]["enabled"])
+        self.assertTrue(result["changed"])
+
+    @patch("cordis_bridge.setup._host_executable", return_value="claude")
+    @patch("cordis_bridge.setup._run")
+    def test_claude_setup_uses_official_user_scope_cli(self, run, _host) -> None:
+        from subprocess import CompletedProcess
+
+        run.side_effect = [
+            CompletedProcess([], 1, "", "not found"),
+            CompletedProcess([], 0, "added", ""),
+            CompletedProcess([], 0, "connected", ""),
+        ]
+        with patch("cordis_bridge.setup._protocol_path", return_value=Path(self.tempdir.name) / "CLAUDE.md"):
+            result = setup_claude_code(Path(self.tempdir.name) / "claude-state")
+        add = run.call_args_list[1].args[0]
+        self.assertEqual(add[:6], ["claude", "mcp", "add", "--scope", "user", "cordis"])
+        self.assertTrue(result["verified"])
+
+    @patch("cordis_bridge.setup._host_executable", return_value="hermes")
+    @patch("cordis_bridge.setup._run")
+    def test_hermes_setup_confirms_tools_and_verifies_connection(self, run, _host) -> None:
+        from subprocess import CompletedProcess
+
+        run.side_effect = [
+            CompletedProcess([], 1, "missing", ""),
+            CompletedProcess([], 0, "Saved 'cordis'", ""),
+            CompletedProcess([], 0, "Connected", ""),
+        ]
+        with patch("cordis_bridge.setup._protocol_path", return_value=Path(self.tempdir.name) / "AGENTS.md"):
+            result = setup_hermes(Path(self.tempdir.name) / "hermes-state")
+        self.assertEqual(run.call_args_list[1].kwargs["input_text"], "y\n")
+        self.assertTrue(result["verified"])