@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/tools.py

@@ -0,0 +1,272 @@
+"""The tool registry — Agentik_Tools/registry.json + install/remove logic.
+
+Tools are third-party software that lands under `Agentik_Tools/<name>/`. Each
+tool has one home and one invoke command. Source can be the MCP catalog
+(`mcp-catalog.yaml`), a direct npm package spec, or a pre-existing tool the
+installer already shipped (e.g. pdfgen).
+
+The registry is the manifest of what is installed — it is git-tracked, the
+tool payloads are not. On a new machine the bootstrap reads the registry and
+reinstalls exactly the same set.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# --------------------------------------------------------------------------
+# Tool dataclass + registry
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Tool:
+    """One row in Agentik_Tools/registry.json."""
+
+    name: str
+    version: str = ""
+    path: str = ""                              # relative to OMEGA_HOME
+    invoke: str = ""                            # relative path to the binary
+    source: str = ""                            # npm package, mcp:<id>, etc.
+    providers: list[str] = field(default_factory=list)  # provider ids that should see it
+    installed_at: str = ""
+    # Optional extras kept for MCP tools (server config + secret refs).
+    secret_refs: list[str] = field(default_factory=list)
+    enabled: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        # Match the existing registry.json field naming for back-compat
+        # (camelCase for installedAt — see pdfgen entry shipped in the repo).
+        d = asdict(self)
+        d["installedAt"] = d.pop("installed_at", "")
+        return d
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Tool":
+        return Tool(
+            name=str(d.get("name", "")),
+            version=str(d.get("version", "")),
+            path=str(d.get("path", "")),
+            invoke=str(d.get("invoke", "")),
+            source=str(d.get("source", "")),
+            providers=list(d.get("providers", []) or []),
+            installed_at=str(d.get("installedAt", d.get("installed_at", "")) or ""),
+            secret_refs=list(d.get("secret_refs", []) or []),
+            enabled=bool(d.get("enabled", True)),
+        )
+
+
+def _omega_home(explicit: str | Path | None = None) -> Path:
+    return Path(explicit or os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+
+
+class ToolRegistry:
+    """Load, mutate, save Agentik_Tools/registry.json."""
+
+    def __init__(self, omega_home: Path, tools: list[Tool], version: int = 1) -> None:
+        self._home = omega_home
+        self._tools: dict[str, Tool] = {t.name: t for t in tools}
+        self._version = version
+
+    # ----- file io -------------------------------------------------------
+
+    @classmethod
+    def load(cls, omega_home: str | Path | None = None) -> "ToolRegistry":
+        home = _omega_home(omega_home)
+        rfile = home / "Agentik_Tools" / "registry.json"
+        if not rfile.exists():
+            return cls(home, [])
+        data = json.loads(rfile.read_text() or "{}")
+        tools = [Tool.from_dict(t) for t in data.get("tools", [])]
+        return cls(home, tools, version=int(data.get("version", 1)))
+
+    def save(self, omega_home: str | Path | None = None) -> None:
+        home = _omega_home(omega_home) if omega_home is not None else self._home
+        rfile = home / "Agentik_Tools" / "registry.json"
+        rfile.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": self._version,
+            "tools": [t.to_dict() for t in self._tools.values()],
+        }
+        rfile.write_text(json.dumps(payload, indent=2) + "\n")
+
+    # ----- queries -------------------------------------------------------
+
+    def list(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def installed_path(self, name: str) -> Path:
+        tool = self.get(name)
+        if tool is None:
+            raise KeyError(f"tool not registered: {name}")
+        return self._home / tool.path
+
+    # ----- mutations -----------------------------------------------------
+
+    def install(self, tool: Tool) -> Tool:
+        """Register a tool (does not run the installer — see install_from_catalog)."""
+        if not tool.installed_at:
+            tool.installed_at = time.strftime("%Y-%m-%dT%H:%M:%S")
+        self._tools[tool.name] = tool
+        return tool
+
+    def remove(self, name: str) -> bool:
+        return self._tools.pop(name, None) is not None
+
+
+# --------------------------------------------------------------------------
+# MCP catalog → tool install
+# --------------------------------------------------------------------------
+
+
+class CatalogError(RuntimeError):
+    """The catalog is missing or the requested id is unknown."""
+
+
+def load_catalog(omega_home: str | Path | None = None) -> dict[str, Any]:
+    """Read Agentik_SSOT/mcp/mcp-catalog.yaml. Raises CatalogError if missing."""
+    import yaml
+    home = _omega_home(omega_home)
+    path = home / "Agentik_SSOT" / "mcp" / "mcp-catalog.yaml"
+    if not path.exists():
+        raise CatalogError(f"MCP catalog missing: {path}")
+    data = yaml.safe_load(path.read_text()) or {}
+    return data
+
+
+def catalog_entry(catalog: dict[str, Any], mcp_id: str) -> dict[str, Any]:
+    for entry in catalog.get("catalog") or []:
+        if str(entry.get("id")) == mcp_id:
+            return entry
+    raise CatalogError(f"unknown MCP id: {mcp_id}")
+
+
+def install_from_catalog(
+    omega_home: str | Path,
+    mcp_id: str,
+    catalog: dict[str, Any] | None = None,
+    registry: ToolRegistry | None = None,
+) -> Tool:
+    """Install one MCP server from the catalog.
+
+    Concrete steps for `install.method == npx`:
+      1. resolve the npm package from `install.package`
+      2. `npm install -g --prefix Agentik_Tools/<id>/ <package>` — binaries land
+         under `Agentik_Tools/<id>/bin/`
+      3. register the tool in registry.json with `source=mcp:<id>`,
+         `invoke=Agentik_Tools/<id>/bin/<binname>` (first binary in bin/), and
+         `secret_refs` copied from the catalog entry.
+
+    Other install methods are recorded but logged as "no installer wired" — they
+    can be added later without changing the call sites.
+    """
+    home = Path(omega_home)
+    if catalog is None:
+        catalog = load_catalog(home)
+    entry = catalog_entry(catalog, mcp_id)
+
+    install = entry.get("install") or {}
+    method = str(install.get("method", "")).lower()
+    package = str(install.get("package", "")).strip()
+    secret_refs = list(entry.get("secrets") or [])
+
+    tool_dir = home / "Agentik_Tools" / mcp_id
+    tool_dir.mkdir(parents=True, exist_ok=True)
+    bin_dir = tool_dir / "bin"
+
+    invoke = ""
+    version = ""
+
+    if method == "npx" and package:
+        npm = shutil.which("npm")
+        if npm is None:
+            raise RuntimeError("npm not found on PATH — install Node.js to use MCP servers")
+        # npm install -g --prefix <dir> <pkg> places binaries in <dir>/bin/.
+        try:
+            subprocess.run(
+                [npm, "install", "-g", "--prefix", str(tool_dir), package],
+                check=True, capture_output=True, text=True, timeout=600,
+            )
+        except subprocess.CalledProcessError as exc:
+            raise RuntimeError(
+                f"npm install failed for {package}: "
+                f"{(exc.stderr or exc.stdout or '')[:500]}"
+            ) from exc
+        if bin_dir.is_dir():
+            bins = sorted(p for p in bin_dir.iterdir() if p.is_file())
+            if bins:
+                invoke = str(bins[0].relative_to(home))
+        # best-effort version detect: read the installed package's package.json
+        try:
+            pkg_dir = tool_dir / "lib" / "node_modules" / package
+            pkg_json = pkg_dir / "package.json"
+            if pkg_json.exists():
+                version = str(json.loads(pkg_json.read_text()).get("version", ""))
+        except (OSError, json.JSONDecodeError):
+            version = ""
+
+    tool = Tool(
+        name=mcp_id,
+        version=version,
+        path=f"Agentik_Tools/{mcp_id}/",
+        invoke=invoke,
+        source=f"mcp:{mcp_id}" if method else f"catalog:{mcp_id}",
+        secret_refs=secret_refs,
+        installed_at=time.strftime("%Y-%m-%dT%H:%M:%S"),
+    )
+
+    reg = registry if registry is not None else ToolRegistry.load(home)
+    reg.install(tool)
+    reg.save(home)
+    return tool
+
+
+# --------------------------------------------------------------------------
+# Canonical MCP config (Agentik_SSOT/mcp/mcp-config.yaml)
+# --------------------------------------------------------------------------
+
+
+def mcp_config_path(omega_home: str | Path | None = None) -> Path:
+    return _omega_home(omega_home) / "Agentik_SSOT" / "mcp" / "mcp-config.yaml"
+
+
+def load_mcp_config(omega_home: str | Path | None = None) -> dict[str, Any]:
+    import yaml
+    path = mcp_config_path(omega_home)
+    if not path.exists():
+        return {"version": 1, "servers": []}
+    data = yaml.safe_load(path.read_text()) or {}
+    data.setdefault("version", 1)
+    data.setdefault("servers", [])
+    return data
+
+
+def merge_mcp_config(
+    omega_home: str | Path | None,
+    entry: dict[str, Any],
+) -> dict[str, Any]:
+    """Append-or-replace one server entry in mcp-config.yaml. Idempotent."""
+    import yaml
+    data = load_mcp_config(omega_home)
+    servers = data.setdefault("servers", [])
+    eid = entry.get("id")
+    for i, existing in enumerate(servers):
+        if existing.get("id") == eid:
+            servers[i] = entry
+            break
+    else:
+        servers.append(entry)
+    path = mcp_config_path(omega_home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(data, sort_keys=False))
+    return data

package/omega/Agentik_Engine/omega_engine/understand_anything.py

@@ -0,0 +1,275 @@
+"""Understand-Anything bridge — register the Claude Code plugin + consume its graph.
+
+Understand-Anything is a popular Claude Code plugin (27k+ stars) that
+analyses a codebase with a multi-agent pipeline and produces an
+interactive knowledge graph at
+``.understand-anything/knowledge-graph.json``.
+
+It overlaps with OmegaOS's existing graphify integration, but the output
+shape is different (it's much richer — file/function/class/dependency
+nodes, business-domain layer, persona-adaptive views, language-concept
+overlays).
+
+This bridge gives operators a one-command path to:
+
+  1. Install the plugin into Claude Code via the marketplace (uses the
+     same OAuth as everything else — no API key, no separate auth).
+  2. After ``/understand`` runs in Claude Code, consume the resulting
+     ``.understand-anything/knowledge-graph.json`` into OmegaOS's
+     ``GraphRetriever`` (same path we use for graphify) so Oracle /
+     workers can answer "where in the code is X?" via Graph RAG.
+
+What this module does NOT do
+----------------------------
+
+  * Run the analysis pipeline itself — that's Claude Code's job via the
+    plugin. We trigger it (``/understand``) and consume the artefact.
+  * Replace graphify — both can coexist; ``omega graph`` already
+    consumes whichever JSON the operator points at.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+_PLUGIN_MARKETPLACE = "Lum1104/Understand-Anything"
+_PLUGIN_NAME = "understand-anything"
+_OUTPUT_FILE = "knowledge-graph.json"
+_OUTPUT_DIR = ".understand-anything"
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class UnderstandAnythingError(RuntimeError):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Plugin install (via `claude` CLI's plugin system)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class InstallResult:
+    ok: bool
+    method: str
+    detail: str = ""
+    error: str = ""
+
+
+def is_plugin_installed(home_claude: str | Path | None = None) -> bool:
+    """True iff the plugin dir already exists under ~/.claude/plugins/."""
+    base = Path(home_claude) if home_claude else Path.home() / ".claude"
+    # Claude Code stores marketplaces under plugins/marketplaces/<owner>-<repo>/
+    p = base / "plugins" / "marketplaces"
+    if not p.is_dir():
+        return False
+    # Best-effort match — different versions of Claude Code use slightly
+    # different dir naming conventions.
+    for child in p.iterdir():
+        n = child.name.lower()
+        if "understand-anything" in n or "lum1104" in n:
+            return True
+    return False
+
+
+def install_plugin(
+    *,
+    claude_cmd: str = "claude",
+    timeout_s: int = 120,
+    dry_run: bool = False,
+) -> InstallResult:
+    """Install the Understand-Anything plugin into Claude Code.
+
+    Mirrors the upstream instructions::
+
+        /plugin marketplace add Lum1104/Understand-Anything
+        /plugin install understand-anything
+
+    We invoke them via ``claude -p`` so the existing Max OAuth is the
+    auth — no API key, no marketplace login.
+    """
+    if shutil.which(claude_cmd) is None:
+        return InstallResult(
+            ok=False, method="skip",
+            error=f"`{claude_cmd}` not on PATH — install Claude Code first",
+        )
+    if dry_run:
+        return InstallResult(
+            ok=True, method="dry-run",
+            detail=(
+                f"would run: {claude_cmd} -p "
+                f"'/plugin marketplace add {_PLUGIN_MARKETPLACE} && "
+                f"/plugin install {_PLUGIN_NAME}'"
+            ),
+        )
+    # Two slash commands, one session.
+    prompt = (
+        f"/plugin marketplace add {_PLUGIN_MARKETPLACE}\n"
+        f"/plugin install {_PLUGIN_NAME}"
+    )
+    try:
+        proc = subprocess.run(
+            [claude_cmd, "-p", prompt, "--dangerously-skip-permissions"],
+            check=False, capture_output=True, text=True, timeout=timeout_s,
+        )
+    except subprocess.TimeoutExpired:
+        return InstallResult(
+            ok=False, method="claude-p",
+            error=f"`claude -p` timed out after {timeout_s}s",
+        )
+    if proc.returncode != 0:
+        tail = (proc.stdout + "\n" + proc.stderr).strip()[-400:]
+        return InstallResult(
+            ok=False, method="claude-p",
+            error=f"claude exited {proc.returncode}\n{tail}",
+        )
+    return InstallResult(
+        ok=True, method="claude-p",
+        detail=f"installed {_PLUGIN_NAME} from {_PLUGIN_MARKETPLACE}",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Trigger an analysis run + consume the output
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunResult:
+    ok: bool
+    output_path: str = ""
+    nodes: int = 0
+    edges: int = 0
+    error: str = ""
+    elapsed_s: float = 0.0
+
+
+def run(
+    project_path: str | Path,
+    *,
+    claude_cmd: str = "claude",
+    language: str | None = None,
+    timeout_s: int = 1800,
+) -> RunResult:
+    """Trigger ``/understand`` in the given project directory.
+
+    Returns a RunResult pointing at the produced
+    ``.understand-anything/knowledge-graph.json`` and a node/edge count.
+    """
+    start = time.time()
+    project = Path(project_path).resolve()
+    if not project.is_dir():
+        return RunResult(ok=False, error=f"not a directory: {project}")
+    if shutil.which(claude_cmd) is None:
+        return RunResult(
+            ok=False,
+            error=f"`{claude_cmd}` not on PATH — install Claude Code first",
+        )
+    prompt = "/understand"
+    if language:
+        prompt += f" --language {language}"
+    try:
+        proc = subprocess.run(
+            [claude_cmd, "-p", prompt, "--add-dir", str(project),
+             "--dangerously-skip-permissions"],
+            check=False, capture_output=True, text=True, timeout=timeout_s,
+            cwd=str(project),
+        )
+    except subprocess.TimeoutExpired:
+        return RunResult(
+            ok=False, elapsed_s=round(time.time() - start, 2),
+            error=f"claude -p /understand timed out after {timeout_s}s",
+        )
+    if proc.returncode != 0:
+        tail = (proc.stdout + "\n" + proc.stderr).strip()[-400:]
+        return RunResult(
+            ok=False, elapsed_s=round(time.time() - start, 2),
+            error=f"claude exited {proc.returncode}\n{tail}",
+        )
+    out = project / _OUTPUT_DIR / _OUTPUT_FILE
+    if not out.exists():
+        return RunResult(
+            ok=False, elapsed_s=round(time.time() - start, 2),
+            error=f"expected output not found at {out}",
+        )
+    nodes, edges = _count_graph(out)
+    return RunResult(
+        ok=True, output_path=str(out),
+        nodes=nodes, edges=edges,
+        elapsed_s=round(time.time() - start, 2),
+    )
+
+
+def _count_graph(path: Path) -> tuple[int, int]:
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return 0, 0
+    if not isinstance(data, dict):
+        return 0, 0
+    n = len(data.get("nodes") or [])
+    e = len(data.get("edges") or data.get("links") or [])
+    return n, e
+
+
+# ---------------------------------------------------------------------------
+# Consume the produced graph into GraphRetriever
+# ---------------------------------------------------------------------------
+
+
+def consume_graph(
+    project_path: str | Path,
+    *,
+    omega_home: str | Path | None = None,
+) -> dict[str, Any]:
+    """Merge the knowledge-graph.json into OmegaOS's GraphRetriever.
+
+    Format adapter: Understand-Anything emits ``{nodes: [{id, type, …}],
+    edges: [{from, to, kind, …}]}``; we map that onto the engine's
+    ``GraphRetriever`` interface (which already powers the graphify
+    consumer at ``omega graph <path>``).
+
+    Returns ``{nodes, edges, written_to}``.
+    """
+    import os as _os
+    project = Path(project_path).resolve()
+    out = project / _OUTPUT_DIR / _OUTPUT_FILE
+    if not out.exists():
+        raise UnderstandAnythingError(
+            f"no graph at {out} — run `omega ua run {project}` first"
+        )
+    try:
+        data = json.loads(out.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise UnderstandAnythingError(f"unreadable graph at {out}: {exc}") from exc
+
+    nodes = data.get("nodes") or []
+    edges = data.get("edges") or data.get("links") or []
+
+    # Project into the engine's memory dir.
+    home = Path(omega_home or _os.environ.get(
+        "OMEGA_HOME", str(Path.home() / "Omega")
+    ))
+    mem = home / "Agentik_Runtime" / "memory"
+    mem.mkdir(parents=True, exist_ok=True)
+    dest = mem / "understand-anything.graph.json"
+    # Normalised shape — same as graphify's output, so GraphRetriever
+    # can consume it via the existing ``omega graph`` pipeline.
+    normalised = {
+        "format": "understand-anything",
+        "source_project": str(project),
+        "nodes": nodes,
+        "edges": edges,
+    }
+    dest.write_text(json.dumps(normalised, indent=2))
+    return {"nodes": len(nodes), "edges": len(edges), "written_to": str(dest)}

package/omega/Agentik_Engine/omega_engine/updater.py

@@ -0,0 +1,70 @@
+"""Update checker — is a newer @agentikos/omega-os out?
+
+Queries the npm registry for the latest published version, compares
+against the running version. Pure-stdlib HTTP (no requests).
+
+CLI surface:
+
+  * ``omega update --check``    — print current + latest, exit 0
+  * ``omega update --apply``    — re-run install.sh --force (delegates
+                                   to ``omega upgrade`` which already
+                                   handles that path)
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+_REGISTRY = "https://registry.npmjs.org/@agentikos%2Fomega-os"
+
+
+@dataclass
+class UpdateInfo:
+    current: str
+    latest: str
+    is_outdated: bool
+    error: str = ""
+
+
+def _parse_semver(v: str) -> tuple[int, int, int]:
+    """Best-effort semver parse. Non-numeric components → 0."""
+    parts = v.split("-")[0].split(".")[:3]
+    out: list[int] = []
+    for p in parts:
+        try:
+            out.append(int(p))
+        except ValueError:
+            out.append(0)
+    while len(out) < 3:
+        out.append(0)
+    return out[0], out[1], out[2]
+
+
+def check_for_updates(current: str, *, timeout: int = 10) -> UpdateInfo:
+    """Compare ``current`` against the npm registry."""
+    try:
+        req = urllib.request.Request(
+            _REGISTRY,
+            headers={"Accept": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        return UpdateInfo(
+            current=current, latest="?", is_outdated=False,
+            error=f"HTTP {exc.code}: {exc.reason}",
+        )
+    except Exception as exc:  # noqa: BLE001
+        return UpdateInfo(
+            current=current, latest="?", is_outdated=False,
+            error=f"network: {exc}"[:200],
+        )
+
+    latest = (data.get("dist-tags") or {}).get("latest", "?")
+    return UpdateInfo(
+        current=current, latest=latest,
+        is_outdated=_parse_semver(current) < _parse_semver(latest),
+    )