diff --git a/.agents/hooks.json b/.agents/hooks.json index 0023dec..97fca8b 100644 --- a/.agents/hooks.json +++ b/.agents/hooks.json @@ -3,11 +3,11 @@ "enabled": true, "PreToolUse": [ { - "matcher": "run_command|grep_search", + "matcher": "run_command|grep_search|view_file", "hooks": [ { "type": "command", - "command": "/Users/aparv/Library/CloudStorage/OneDrive-Personal/G-Drive/Interviews/knowledge/DSA/.agents/scripts/hook_pre_tool.sh", + "command": "./scripts/hook_pre_tool.sh", "timeout": 5 } ] @@ -16,16 +16,16 @@ "PreInvocation": [ { "type": "command", - "command": "/Users/aparv/Library/CloudStorage/OneDrive-Personal/G-Drive/Interviews/knowledge/DSA/.agents/scripts/hook_pre_invocation.sh", + "command": "./scripts/hook_pre_invocation.sh", "timeout": 5 } ], "Stop": [ { "type": "command", - "command": "/Users/aparv/Library/CloudStorage/OneDrive-Personal/G-Drive/Interviews/knowledge/DSA/.agents/scripts/hook_stop.sh", + "command": "./scripts/hook_stop.sh", "timeout": 5 } ] } -} +} \ No newline at end of file diff --git a/.agents/rules/00-omni-graph-mandatory-retrieval.md b/.agents/rules/00-omni-graph-mandatory-retrieval.md new file mode 100644 index 0000000..a196a6b --- /dev/null +++ b/.agents/rules/00-omni-graph-mandatory-retrieval.md @@ -0,0 +1,108 @@ +# 🧭 Rule 00 β€” Omni-Graph Mandatory Retrieval & Guardrails + +> **Priority**: πŸ”΄ CRITICAL β€” NON-NEGOTIABLE GLOBAL INVARIANT. +> **Scope**: Machine-wide across all 100+ repositories and polyglot codebases (Go, Rust, Python, TypeScript/JavaScript, C/C++, Java, Zig, Elixir, Scala, Swift, Kotlin, Shell, etc.). +> **Order**: Prefixed with `00-` to guarantee top-tier precedence and prevent rule shadowing by downstream repository-specific rules. + +--- + +## 1. Purpose & Core Philosophy + +This entire engineering ecosystem indexes codebases into **Omni-Graph** β€” a high-performance AST knowledge hub backed by SurrealDB v2 and HuggingFace 384-dimensional vector embeddings. + +Language models frequently suffer from **context exhaustion, cognitive drift, and hallucinated references** when attempting to understand code through brute-force text search (`grep -r`), blind directory walking (`find`), or raw whole-file dumping (`cat` / `view_file` on large files). + +**Rule 00 enforces three mandatory structural invariants**: +1. **Never read whole source code files (>150 lines)** without prior AST symbol localization or condensation. +2. **Never refactor or delete symbols** without verifying caller blast radius via `/api/references`. +3. **Never guess multi-file call hierarchies** when compiler AST edges (`CALLS`, `IMPORTS`, `IMPLEMENTS`) exist in the knowledge graph. + +--- + +## 2. Active Guardrails & Gated Tool Policies + +### A. The 150-Line Source Code Gate & 450-Line Documentation Ceiling (`view_file`) +- **Active PreToolUse Interception**: Any call to `view_file` on a source code file without `EndLine` specified or spanning **more than 150 lines** is **automatically BLOCKED** by the guardrail. +- **Calibrated Documentation Ceiling**: For Markdown files (`.md`, `.markdown`), reading without `EndLine` on files $>450$ lines or requesting line spans $>450$ lines is intercepted to prevent context exhaustion, guiding agents to `/api/search`. Small documentation files ($\le 450$ lines) or targeted chapter/section slices ($\le 450$ lines) are permitted. +- **Allowed Actions**: + - βœ… Query symbol definition: `curl -s "http://localhost:8080/api/symbol?name=&workspace="` + - βœ… Extract topological subgraph slice: `curl -s "http://localhost:8080/api/condense?symbol=&workspace=&hops=2"` + - βœ… View focused line slice: `view_file` with `StartLine: X, EndLine: Y` where `(Y - X + 1) <= 150` lines for code or `<= 450` lines for documentation. + - βœ… Reading non-code configs (`.txt`, `.json`, `.yaml`, `.toml`, `.csv`) is unbounded and permitted. + +### B. Prohibited Brute-Force Shell & Grep Scans +- **Recursive Grep Blocked**: `grep -r`, `grep -rn`, `find . -name`, `ag`, `rg` with blanket patterns are actively blocked by PreToolUse. +- **Required Alternative**: + - Semantic vector search: `curl -s "http://localhost:8080/api/search?q=&workspace=&k=5"` + - High-level architectural Q&A: `curl -s "http://localhost:8080/api/query?q=&workspace="` + +### C. Caller Blast-Radius Verification (Before Edits) +- Before renaming, modifying a public signature, or deleting any function, method, struct, or type: + - **MANDATORY**: Run `curl -s "http://localhost:8080/api/references?symbol=&workspace="` + - Review all callers across all files in the repository before making edits. + +### D. Ambient Live Watch & Zero Redundant Ingestion Invariant +- **Live Watch Persistence**: Codebases indexed in Omni-Graph have real-time file watchers active. Edits made by agents or humans are automatically synchronized into AST nodes in SurrealDB within 500ms. +- **Prohibited Action**: Never execute `POST /api/ingest` on a workspace that is already indexed (`total_nodes > 0`) or active under live watch. Always check `GET /api/workspaces` first. Redundant ingestion causes unnecessary disk I/O and CPU churn. + +--- + +## 3. The 3-Tier Omniverse Reconnaissance Ladder + +When tasked with any bug fix, optimization, feature implementation, or codebase exploration: + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ TIER 1: MACROSCOPIC RECONNAISSANCE β”‚ + β”‚ β€’ GET http://localhost:8080/api/workspaces + β”‚ β€’ GET http://localhost:8080/api/query?q=... + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ TIER 2: MESOSCOPIC SUBSYSTEM MAP β”‚ + β”‚ β€’ GET http://localhost:8080/api/galaxies?workspace=... + β”‚ β€’ Inspect Louvain/Leiden modular clusters + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ TIER 3: MICROSCOPIC AST CONDENSATION β”‚ + β”‚ β€’ GET http://localhost:8080/api/symbol?name=... + β”‚ β€’ GET http://localhost:8080/api/references?symbol=... + β”‚ β€’ GET http://localhost:8080/api/condense?symbol=...&hops=2 + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Tier 1: Macroscopic Reconnaissance (Omniverse Discovery) +- **Goal**: Identify which workspace and core files contain the relevant domain logic. +- **Action**: Check workspace status in prompt header or `GET /api/workspaces`. Run hybrid Graph-RAG queries (`/api/query?q=...`) for high-level architectural understanding. + +### Tier 2: Mesoscopic Subsystem Mapping (Galaxy Clusters) +- **Goal**: Map architectural boundaries, component clusters, and dependencies without reading files. +- **Action**: Query `/api/galaxies?workspace=` to view detected community partitions and entrypoint symbols. + +### Tier 3: Microscopic AST Condensation (<1500 Tokens) +- **Goal**: Extract pinpoint function signatures, line numbers, and directional call graphs. +- **Action**: Use `/api/symbol`, `/api/references`, and `/api/condense` to get high-density prompt slices (<1,500 tokens). + +--- + +## 4. Decision Matrix: Polyglot Action Guide + +| Scenario / Intent | ❌ Prohibited Anti-Pattern | βœ… Mandatory Omni-Graph Action | +|---|---|---| +| Exploring a codebase | `view_file` on entire files (>150 lines) | `/api/galaxies` or `/api/workspaces` | +| Understanding algorithm / logic | Blind reading of 5–10 files | `/api/condense?symbol=&hops=2` | +| Finding a symbol definition | `grep -rn "func Solve" .` | `/api/symbol?name=Solve&workspace=` | +| Finding all callers of a function | `grep -rn "Solve(" .` | `/api/references?symbol=Solve&workspace=` | +| Conceptual / fuzzy search | Raw text regex across repository | `/api/search?q=&workspace=` | +| Inspecting implementation | `view_file` without line numbers | `view_file` with `StartLine` & `EndLine` (<= 150 lines) | + +--- + +## 5. Fail-Safe Liveness Policy + +- If the Omni-Graph server (`http://localhost:8080/api/health`) is temporarily unreachable: + - Guardrail hooks **fail-open** to ensure agent continuity. + - However, agents should attempt to start the stack via `make -C tools/omni-graph up` (or `docker compose -f tools/omni-graph/docker-compose.yml up -d`) to restore high-density AST capabilities. diff --git a/.agents/rules/08-omni-graph-enforcement.md b/.agents/rules/08-omni-graph-enforcement.md deleted file mode 100644 index 8b34e0e..0000000 --- a/.agents/rules/08-omni-graph-enforcement.md +++ /dev/null @@ -1,94 +0,0 @@ -# 🧭 Rule 08 β€” Omni-Graph Architectural Enforcement & Navigation - -> **Priority**: πŸ”΄ Critical β€” Structure-First Navigation Over Brute-Force Scanning. -> This rule is mandatory for all coding agents operating in this repository. - ---- - -## 1. Purpose & Core Philosophy - -This monorepo indexes codebases into **Omni-Graph** β€” a deterministic AST knowledge hub backed by SurrealDB v2 and HuggingFace 384-d semantic embeddings. - -AI coding agents often suffer from **cognitive drift and context exhaustion** when blindly executing recursive `grep -rn`, whole-folder `find`, or dumping large multi-file `cat` outputs into the prompt. - -**Rule 08 strictly mandates structure-first, high-signal retrieval**: -- Never read 50,000 tokens of raw source code to answer what a 600-token condensed AST slice proves deterministically. -- Never guess function callers or line ranges with regex when directional AST edges (`CALLS`, `IMPORTS`, `IMPLEMENTS`) exist in the knowledge graph. - ---- - -## 2. The 3-Tier Omniverse Reconnaissance Ladder - -When investigating an unfamiliar codebase, feature request, or bug report, follow the **3-Tier Ladder** in order: - -``` - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ TIER 1: MACROSCOPIC RECONNAISSANCE β”‚ - β”‚ β€’ make workspaces β”‚ - β”‚ β€’ make query-graph Q="..." β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ TIER 2: MESOSCOPIC SUBSYSTEM MAP β”‚ - β”‚ β€’ make graph-galaxies PROJECT=... β”‚ - β”‚ β€’ Filter by architectural cluster β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ TIER 3: MICROSCOPIC AST CONDENSATION β”‚ - β”‚ β€’ make graph-symbol SYM=... β”‚ - β”‚ β€’ make graph-references SYM=... β”‚ - β”‚ β€’ make graph-condense SYM=... HOPS=2 β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -### Tier 1: Macroscopic Reconnaissance (Omniverse Discovery) -- **Goal**: Identify which partitioned codebase contains the relevant domain logic. -- **Action**: Run `make workspaces` to see all ingested projects and their language distributions. -- **Hybrid Synthesis**: Run `make query-graph Q="" [PROJECT=name]` to retrieve both a macroscopic architectural synthesis and an expanded call subgraph in a single prompt slice. - -### Tier 2: Mesoscopic Subsystem Mapping (Galaxy Clusters) -- **Goal**: Understand the architectural boundaries, modules, and subsystems without reading files. -- **Action**: Run `make graph-galaxies [PROJECT=name]` (or `./scripts/omni.sh galaxies [ws]`). -- **Inspection**: Review detected Louvain/Leiden community clusters, dominant package paths, node counts, and key entrypoint symbols. - -### Tier 3: Microscopic AST Condensation (<1500 Tokens) -- **Goal**: Extract exact function signatures, line ranges, and directional call graphs without noise. -- **Symbol Definition**: Run `make graph-symbol SYM= [PROJECT=name]`. -- **Caller Lineage**: Run `make graph-references SYM= [PROJECT=name]` to find every caller in the codebase. -- **Multi-Hop AST Slice**: Run `make graph-condense SYM= [HOPS=2] [PROJECT=name]` to extract a dense, verified markdown slice ready to insert into reasoning. - ---- - -## 3. Decision Matrix: Which Tool to Use When - -| Agent Goal / Scenario | ❌ Prohibited Anti-Pattern | βœ… Mandatory Omni-Graph Action | -|---|---|---| -| Exploring a new repository | `ls -R`, recursive `find .` | `make workspaces` + `make graph-galaxies PROJECT=` | -| Asking "How does X work?" | Reading 10 source files sequentially | `make query-graph Q="How does X work?" PROJECT=` | -| Finding where a function is defined | `grep -rn "def init_pool" .` | `make graph-symbol SYM=init_pool [PROJECT=]` | -| Finding all callers of an API | `grep -rn "init_pool" .` | `make graph-references SYM=init_pool [PROJECT=]` | -| Tracing multi-file call chains | Reading files and following imports manually | `make graph-condense SYM=init_pool HOPS=2` | -| Fuzzy / Conceptual code search | Blind regex across directory | `make search-graph Q="database connection pool"` | - ---- - -## 4. Guardrail & Lifecycle Hook Adherence - -1. **PreToolUse Interception**: - - The repo configuration in `.agents/hooks.json` intercepts whole-repo `grep` and `find` commands. - - If a guardrail hook denies a tool call with guidance to use Omni-Graph, **never attempt to circumvent or rephrase the grep**. Immediately switch to the indicated Omni-Graph command. -2. **PreInvocation Awareness**: - - When the ephemeral notification `🧭 [Omni-Graph Active]` is present in system context, Omni-Graph is online and ready for queries on port 8080. -3. **Fail-Safe Recovery**: - - If the Omni-Graph stack is offline (`Connection error`), start it with `make omni-graph` (or `make -C tools/omni-graph up`) before proceeding. - ---- - -## 5. Token Budgeting Protocols - -- **Floor**: Aim for <1,500 tokens of high-fidelity code context per investigation step. -- **Density**: Use `make graph-condense` which strips file fluff and retains AST-typed relationships (`CALLS`, `IMPORTS`, `IMPLEMENTS`). -- **Precision**: Only open raw full source files via `view_file` when actively writing code edits or modifying lines after AST localization has pin-pointed the target slice. diff --git a/.agents/scripts/hook_pre_invocation.sh b/.agents/scripts/hook_pre_invocation.sh index 36d402e..fc9d9b4 100755 --- a/.agents/scripts/hook_pre_invocation.sh +++ b/.agents/scripts/hook_pre_invocation.sh @@ -1,24 +1,224 @@ #!/usr/bin/env bash # ============================================================================== -# Omni-Graph PreInvocation Hook -# Injects ephemeral system guidance alerting the model that Omni-Graph AST -# knowledge hub is online for semantic search and call tracing. +# Omni-Graph PreInvocation Hook (High-Density / Zero-Fluff) +# Dynamically resolves active workspace from CLI payload (workspacePaths) or CWD, +# debounces duplicate hook executions (<1.5s per conversation), and injects an +# ultra-compact (<50 token) AST endpoint cheat-sheet into the agent prompt. # ============================================================================== set -e -# Fast check if Omni-Graph API is responding on port 8080 -if curl -sf --connect-timeout 1 http://localhost:8080/api/health >/dev/null 2>&1; then - cat << 'EOF' -{ - "injectSteps": [ - { - "ephemeralMessage": "🧭 [Omni-Graph Active]: Query http://localhost:8080/api/search or /api/graph for structural code intelligence instead of raw text file walking." - } - ] -} +PAYLOAD=$(cat) + +python3 - "$PAYLOAD" << 'EOF' +import sys, json, os, subprocess, urllib.request, time + +try: + # 0. Parse Payload from stdin + raw_input = sys.argv[1] if len(sys.argv) > 1 else sys.stdin.read() + data = json.loads(raw_input) if raw_input.strip() else {} + + # Idempotency Guard: Debounce duplicate hook triggers (<1.5s) if both + # local (.agents) and global (~/.gemini/config) hooks execute on the same turn + conv_id = data.get("conversationId", "default") + marker = f"/tmp/omni_pre_inv_{conv_id}.last" + now = time.time() + try: + if os.path.exists(marker): + with open(marker, "r") as f: + last_ts = float(f.read().strip()) + if (now - last_ts) < 1.5: + print(json.dumps({"injectSteps": []})) + sys.exit(0) + with open(marker, "w") as f: + f.write(str(now)) + except Exception: + pass + + # 1. Daemon Liveness Check (fast 500ms timeout) + req = urllib.request.Request("http://localhost:8080/api/health", headers={"User-Agent": "OmniHook/1.0"}) + with urllib.request.urlopen(req, timeout=0.5) as resp: + if resp.status != 200: + print(json.dumps({"injectSteps": []})) + sys.exit(0) + + # 2. Dynamically determine active workspace root directory + active_dir = "" + ws_paths = data.get("workspacePaths", []) + if ws_paths and isinstance(ws_paths, list) and ws_paths[0]: + active_dir = ws_paths[0] + + if not active_dir: + active_dir = os.environ.get("WORKSPACE_CWD") or os.environ.get("WORKSPACE") or "" + + if not active_dir: + active_dir = os.getcwd() + + git_root = "" + try: + git_root = subprocess.check_output( + ["git", "-C", active_dir, "rev-parse", "--show-toplevel"], + stderr=subprocess.DEVNULL, + encoding="utf-8" + ).strip() + ws_candidate = os.path.basename(git_root) + except Exception: + ws_candidate = os.path.basename(active_dir) + + target_dir = git_root or active_dir + + # Detect if working inside a Git Worktree + wt_info = None + git_file = os.path.join(git_root, ".git") if git_root else os.path.join(target_dir, ".git") + if os.path.isfile(git_file): + try: + with open(git_file, "r") as gf: + first_line = gf.readline().strip() + if first_line.startswith("gitdir:"): + gitdir_path = first_line[7:].strip() + if not os.path.isabs(gitdir_path): + gitdir_path = os.path.normpath(os.path.join(os.path.dirname(git_file), gitdir_path)) + head_file = os.path.join(gitdir_path, "HEAD") + branch = "detached" + if os.path.isfile(head_file): + with open(head_file, "r") as hf: + head_line = hf.readline().strip() + if head_line.startswith("ref: refs/heads/"): + branch = head_line[16:] + parts = gitdir_path.replace("\\", "/").split("/") + parent_ws = "parent" + if ".git" in parts: + idx = parts.index(".git") + if idx > 0: + parent_ws = parts[idx - 1] + wt_name = os.path.basename(git_root) or os.path.basename(target_dir) + wt_info = { + "is_worktree": True, + "worktree_name": wt_name, + "parent_workspace": parent_ws, + "branch": branch + } + except Exception: + pass + + # 3. Query workspaces from Omni-Graph + req_ws = urllib.request.Request("http://localhost:8080/api/workspaces", headers={"User-Agent": "OmniHook/1.0"}) + workspaces = [] + with urllib.request.urlopen(req_ws, timeout=0.8) as resp_ws: + workspaces = json.loads(resp_ws.read().decode("utf-8")) + + # Cache list of indexed workspace names for fast PreToolUse lookup + try: + indexed_names = [w.get("workspace") for w in workspaces if w.get("total_nodes", 0) > 0] + for w in workspaces: + for wt in w.get("worktrees", []): + if wt.get("total_nodes", 0) > 0: + indexed_names.append(wt.get("workspace")) + with open("/tmp/omni_indexed_workspaces.json", "w") as f: + json.dump(indexed_names, f) + except Exception: + pass + + matched_ws = None + node_count = 0 + matched_entry = None + + norm_active = os.path.realpath(target_dir).lower() + for w in workspaces: + root_path = w.get("root_path", "") + norm_root = os.path.realpath(root_path).lower() if root_path else "" + if norm_root and (norm_active == norm_root or norm_active.startswith(norm_root + "/")): + matched_ws = w.get("workspace") + node_count = w.get("total_nodes", 0) + matched_entry = w + break + for wt in w.get("worktrees", []): + wt_root = wt.get("root_path", "") + norm_wt_root = os.path.realpath(wt_root).lower() if wt_root else "" + if norm_wt_root and (norm_active == norm_wt_root or norm_active.startswith(norm_wt_root + "/")): + matched_ws = wt.get("workspace") + node_count = wt.get("total_nodes", 0) + matched_entry = wt + break + if matched_ws: + break + + if not matched_ws: + for w in workspaces: + if w.get("workspace", "").lower() == ws_candidate.lower(): + matched_ws = w.get("workspace") + node_count = w.get("total_nodes", 0) + matched_entry = w + break + for wt in w.get("worktrees", []): + if wt.get("workspace", "").lower() == ws_candidate.lower(): + matched_ws = wt.get("workspace") + node_count = wt.get("total_nodes", 0) + matched_entry = wt + break + if matched_ws: + break + + if not matched_ws: + matched_ws = ws_candidate + + if node_count > 0: + try: + with open(f"/tmp/omni_indexed_{matched_ws}.flag", "w") as f: + f.write(str(node_count)) + except Exception: + pass + + is_watching = matched_entry.get("is_watching", False) if matched_entry else False + if not is_watching: + try: + watch_payload = json.dumps({"workspace": matched_ws, "path": target_dir}).encode("utf-8") + watch_req = urllib.request.Request( + "http://localhost:8080/api/watch/start", + data=watch_payload, + headers={"Content-Type": "application/json", "User-Agent": "OmniHook/1.0"} + ) + urllib.request.urlopen(watch_req, timeout=0.8) + is_watching = True + except Exception: + pass + + wt_suffix = f" (worktree: {wt_info['branch']} -> {wt_info['parent_workspace']})" if wt_info else "" + watch_str = " | live-watch: ON" if is_watching else "" + msg = ( + f"🧭 Omni-Graph | ws: {matched_ws}{wt_suffix} ({node_count:,} nodes{watch_str})\n" + f"Endpoints (:8080/api): /query (Graph-RAG) | /galaxies | /condense?symbol=X | /references?symbol=X | /symbol?name=X | /search?q=X\n" + f"[Gate: direct source reads >150 lines blocked β€” query AST endpoints first]" + ) + else: + try: + flag = f"/tmp/omni_indexed_{matched_ws}.flag" + if os.path.exists(flag): + os.remove(flag) + except Exception: + pass + + if wt_info: + msg = ( + f"🧭 Omni-Graph | unindexed worktree: {matched_ws} ({wt_info['branch']} -> {wt_info['parent_workspace']})\n" + f"β€’ Ingest: curl -s -X POST http://localhost:8080/api/ingest -H 'Content-Type: application/json' -d '{{\"path\": \"{target_dir}\", \"watch\": true}}'\n" + f"[Auto-inherits galaxy seeds from parent: {wt_info['parent_workspace']}]" + ) + else: + msg = ( + f"🧭 Omni-Graph | ws: {matched_ws} (unindexed)\n" + f"β€’ Ingest: curl -s -X POST http://localhost:8080/api/ingest -H 'Content-Type: application/json' -d '{{\"path\": \"{target_dir}\", \"watch\": true}}'\n" + f"[Note: Index once; live-watch auto-syncs. Never re-ingest an active workspace.]" + ) + + print(json.dumps({ + "injectSteps": [ + { + "ephemeralMessage": msg + } + ] + })) + +except Exception: + print(json.dumps({"injectSteps": []})) EOF -else - # Output empty injectSteps when offline - echo '{"injectSteps": []}' -fi diff --git a/.agents/scripts/hook_pre_tool.sh b/.agents/scripts/hook_pre_tool.sh index 778b03c..d97f2b4 100755 --- a/.agents/scripts/hook_pre_tool.sh +++ b/.agents/scripts/hook_pre_tool.sh @@ -1,54 +1,294 @@ #!/usr/bin/env bash # ============================================================================== -# Omni-Graph PreToolUse Guardrail Hook -# Intercepts brute-force grep/cat that burn LLM context windows and guides -# the agent towards AST-indexed semantic search and graph traversal. +# Omni-Graph PreToolUse Guardrail Hook (Zero-Fluff / High-Density) +# Intercepts brute-force grep, un-reconnoitered source access, and unbounded +# source file reads (>150 lines). Enforces Session-Scoped Recon Gate. # ============================================================================== set -e -# Read hook payload from stdin PAYLOAD=$(cat) -# Extract tool name and command using lightweight python / awk -python3 -c ' -import sys, json +python3 - "$PAYLOAD" << 'EOF' +import sys, json, os, urllib.request, time, subprocess, re try: - data = json.loads(sys.argv[1]) if len(sys.argv) > 1 else json.load(sys.stdin) + # 0. Parse Tool Call Payload + raw_input = sys.argv[1] if len(sys.argv) > 1 else sys.stdin.read() + data = json.loads(raw_input) if raw_input.strip() else {} tool_call = data.get("toolCall", {}) tool_name = tool_call.get("name", "") args = tool_call.get("args", {}) - cmd = args.get("CommandLine", "") - query = args.get("Query", "") - search_path = args.get("SearchPath", "") + # Hard Block: browser_subagent causes language server IPC deadlocks/crashes + if tool_name == "browser_subagent": + print(json.dumps({ + "decision": "deny", + "reason": "BLOCKED: browser_subagent is disabled (causes LS crashes). Use Playwright MCP or run_command." + })) + sys.exit(0) + + # 1. Daemon Liveness Check (Fail-Open Safeguard) + try: + req = urllib.request.Request("http://localhost:8080/api/health", headers={"User-Agent": "OmniHook/1.0"}) + with urllib.request.urlopen(req, timeout=0.5) as resp: + if resp.status != 200: + print(json.dumps({"decision": "allow"})) + sys.exit(0) + except Exception: + print(json.dumps({"decision": "allow"})) + sys.exit(0) + + RECON_TTL = 7200 # 2 hours + + def is_workspace_indexed(workspace): + if not workspace: + return False + if os.path.exists(f"/tmp/omni_indexed_{workspace}.flag"): + return True + try: + with open("/tmp/omni_indexed_workspaces.json", "r") as f: + indexed = json.load(f) + return workspace in indexed + except Exception: + return workspace in {"PolyTuring", "tool-scripts", "session-explorer", "k8s-eks", "python", "tutor-intelligence", "DSA"} + + def get_workspace(target_path=""): + ws = os.environ.get("WORKSPACE") + if ws: + return ws + + if target_path: + norm = target_path.replace("\\", "/") + for part in reversed(norm.split("/")): + if part and is_workspace_indexed(part): + return part + + for k in ("Cwd", "SearchPath", "TargetFile", "AbsolutePath"): + val = args.get(k, "") + if val: + norm = val.replace("\\", "/") + for part in reversed(norm.split("/")): + if part and is_workspace_indexed(part): + return part - # Detect whole-repo brute force text search patterns - is_brute_force = False - reason = "" + ws_paths = data.get("workspacePaths", []) + if ws_paths: + for wp in ws_paths: + norm = wp.replace("\\", "/") + for part in reversed(norm.split("/")): + if part and is_workspace_indexed(part): + return part + base = os.path.basename(wp) + if base: + return base + base_dir = ws_paths[0] if ws_paths else (args.get("Cwd") or "") + try: + git_cmd = ["git", "-C", base_dir, "rev-parse", "--show-toplevel"] if base_dir else ["git", "rev-parse", "--show-toplevel"] + git_root = subprocess.check_output( + git_cmd, + stderr=subprocess.DEVNULL, + encoding="utf-8" + ).strip() + return os.path.basename(git_root) + except Exception: + if base_dir: + return os.path.basename(base_dir) + return os.path.basename(os.getcwd()) or "default" + + def is_recon_done(workspace): + keys = [workspace] if workspace and workspace != "default" else ["default"] + for ws_key in keys: + marker = f"/tmp/omni_recon_{ws_key}.marker" + try: + with open(marker, "r") as f: + ts = int(f.read().strip()) + if (int(time.time()) - ts) < RECON_TTL: + return True + except Exception: + continue + return False + + def record_recon(workspace): + now = str(int(time.time())) + for ws_key in filter(None, [workspace]): + try: + with open(f"/tmp/omni_recon_{ws_key}.marker", "w") as f: + f.write(now) + except Exception: + pass + + NON_CODE_EXTS = { + ".md", ".markdown", ".mdown", ".mkd", ".txt", ".text", + ".json", ".json5", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf", + ".csv", ".tsv", ".svg", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".webp", + ".lock", ".sum", ".env", ".example", ".sample", ".pdf", ".mp4", ".mov", + ".log", ".tmp", ".bak", ".patch", ".diff", ".pid", ".socket", ".wasm", + ".bin", ".exe", ".o", ".a", ".so", ".dylib", ".dll", ".class", ".jar" + } + + NON_CODE_FILENAMES = { + "makefile", "dockerfile", "docker-compose.yml", "docker-compose.yaml", + "license", "licence", "readme", "notice", "authors", "contributors", + "cargo.lock", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", + "go.sum", "gemfile.lock", "poetry.lock", "mix.lock" + } + + def is_source_code(file_path): + if not file_path: + return False + normalized = file_path.replace("\\", "/") + if "/.agents/" in normalized or "/.gemini/" in normalized or "/.git/" in normalized: + return False + base = os.path.basename(file_path).lower() + if base in NON_CODE_FILENAMES: + return False + _, ext = os.path.splitext(base) + if ext in NON_CODE_EXTS: + return False + return True + + # 3. Intercept run_command if tool_name == "run_command": - if any(p in cmd for p in ["grep -r", "grep -rn", "find . -name", "cat $(find"]): - is_brute_force = True - reason = "Blind recursive text scanning detected. Omni-Graph is active β€” query semantic vector search (GET http://localhost:8080/api/search?q=...) or symbol endpoints instead." + cmd = args.get("CommandLine", "") + + omni_patterns = [ + "localhost:8080/api/symbol", "127.0.0.1:8080/api/symbol", + "localhost:8080/api/condense", "127.0.0.1:8080/api/condense", + "localhost:8080/api/references", "127.0.0.1:8080/api/references", + "localhost:8080/api/search", "127.0.0.1:8080/api/search", + "localhost:8080/api/query", "127.0.0.1:8080/api/query", + "localhost:8080/api/galaxy", "127.0.0.1:8080/api/galaxy", + "localhost:8080/api/ast", "127.0.0.1:8080/api/ast", + "localhost:8080/api/workspaces", "127.0.0.1:8080/api/workspaces", + "localhost:8080/api/ingest", "127.0.0.1:8080/api/ingest", + "make graph-", "make search-graph", "make query-graph", + "omni.sh", "scripts/omni", "make workspaces" + ] + if any(p in cmd for p in omni_patterns): + ws = get_workspace() + record_recon(ws) + ws_match = re.search(r'(?:workspace|PROJECT)=([a-zA-Z0-9_-]+)', cmd) + if ws_match: + record_recon(ws_match.group(1)) + + blocked_patterns = [ + "grep -r", "grep -rn", "grep -ri", "grep -rin", "grep -rIn", + "find . -name", "cat $(find", "ag -l", "rg -l" + ] + if any(p in cmd for p in blocked_patterns): + print(json.dumps({ + "decision": "deny", + "reason": "BLOCKED: Blind recursive search. Query Omni-Graph: :8080/api/search?q=X or :8080/api/symbol?name=X." + })) + sys.exit(0) + # 4. Intercept view_file and read_file (150-line gate & AST recon gate) + elif tool_name in ("view_file", "read_file"): + target_path = args.get("AbsolutePath", "") or args.get("Path", "") + ws = get_workspace(target_path) + if is_source_code(target_path): + if is_workspace_indexed(ws) and not is_recon_done(ws): + print(json.dumps({ + "decision": "deny", + "reason": f"🧭 Omni-Graph recon required for {os.path.basename(target_path)} (ws: {ws}). Query :8080/api/symbol?name=X, /condense?symbol=X, or /search?q=X first." + })) + sys.exit(0) + + start_line = args.get("StartLine") + end_line = args.get("EndLine") + + if end_line is None: + print(json.dumps({ + "decision": "deny", + "reason": "BLOCKED: Direct reading >150 lines of source code exhausts context. Query :8080/api/symbol?name=X or /condense?symbol=X, or specify EndLine <= 150." + })) + sys.exit(0) + + try: + start = int(start_line) if start_line is not None else 1 + end = int(end_line) + span = end - start + 1 + if span > 150: + print(json.dumps({ + "decision": "deny", + "reason": f"BLOCKED: Slice of {span} lines exceeds the 150-line gate. Query :8080/api/symbol?name=X or narrow slice to <= 150 lines." + })) + sys.exit(0) + except (ValueError, TypeError): + pass + + elif target_path and any(target_path.lower().endswith(ext) for ext in [".md", ".markdown", ".mdown", ".mkd"]): + start_line = args.get("StartLine") + end_line = args.get("EndLine") + + if end_line is None: + try: + with open(target_path, "r", encoding="utf-8", errors="ignore") as f: + line_count = sum(1 for _ in f) + if line_count > 450: + print(json.dumps({ + "decision": "deny", + "reason": f"BLOCKED: Markdown '{os.path.basename(target_path)}' has {line_count} lines (>450 ceiling). Query :8080/api/search?q=X&workspace={ws} or narrow slice to <= 450 lines." + })) + sys.exit(0) + except Exception: + pass + else: + try: + start = int(start_line) if start_line is not None else 1 + end = int(end_line) + span = end - start + 1 + if span > 450: + print(json.dumps({ + "decision": "deny", + "reason": f"BLOCKED: Slice of {span} lines exceeds 450-line documentation limit. Narrow slice to <= 450 lines or query :8080/api/search." + })) + sys.exit(0) + except (ValueError, TypeError): + pass + + # 5. Intercept grep_search elif tool_name == "grep_search": - if query.strip() == "" or len(query) < 2: - is_brute_force = True - reason = "Broad blanket grep search without target query detected. Use Omni-Graph AST symbol & reference endpoints (GET http://localhost:8080/api/symbol?name=...)." + search_path = args.get("SearchPath", "") + ws = get_workspace(search_path) + query = args.get("Query", "").strip() + includes = args.get("Includes", []) - if is_brute_force: - print(json.dumps({ - "decision": "deny", - "reason": reason - })) - else: - print(json.dumps({ - "decision": "allow" - })) + is_markdown_grep = any(inc.lower().endswith(ext) for inc in includes for ext in [".md", ".markdown"]) if includes else False + if is_markdown_grep and is_workspace_indexed(ws) and not is_recon_done(ws): + print(json.dumps({ + "decision": "deny", + "reason": f"🧭 Omni-Graph recon recommended before searching docs in ws: {ws}. Query :8080/api/search?q={query}&workspace={ws}." + })) + sys.exit(0) + + is_non_code_search = False + normalized_path = search_path.replace("\\", "/") + if "/.agents" in normalized_path or "/.gemini" in normalized_path or "/.git" in normalized_path: + is_non_code_search = True + elif search_path and os.path.isfile(search_path) and not is_source_code(search_path): + is_non_code_search = True + elif includes and all(any(inc.lower().endswith(ext) for ext in NON_CODE_EXTS) for inc in includes): + is_non_code_search = True + + if not is_non_code_search and is_workspace_indexed(ws) and not is_recon_done(ws): + print(json.dumps({ + "decision": "deny", + "reason": f"🧭 Omni-Graph recon required for ws: {ws}. Query :8080/api/symbol?name=X, /condense?symbol=X, or /search?q={query}&workspace={ws}." + })) + sys.exit(0) + + if len(query) < 2: + print(json.dumps({ + "decision": "deny", + "reason": "BLOCKED: Empty/broad grep query. Query :8080/api/symbol?name=X or :8080/api/search?q=X." + })) + sys.exit(0) + + print(json.dumps({"decision": "allow"})) -except Exception as e: - # Fail-safe allow so agents are never hard-crashed on script error +except Exception: print(json.dumps({"decision": "allow"})) -' "$PAYLOAD" +EOF diff --git a/.agents/skills/omni-graph/SKILL.md b/.agents/skills/omni-graph/SKILL.md index 393b083..69de31f 100644 --- a/.agents/skills/omni-graph/SKILL.md +++ b/.agents/skills/omni-graph/SKILL.md @@ -6,118 +6,639 @@ description: >- # 🧭 Omni-Graph Codebase Intelligence Skill -This skill gives coding agents **deterministic AST analysis, multi-workspace exploration, and vector similarity search** across indexed codebases, condensing multi-file call chains into high-signal prompt slices (<1,500 tokens). +This skill equips AI coding assistants with **deterministic compiler AST analysis, multi-workspace exploration, personalized PageRank call graph condensation, and dense vector semantic search** across indexed polyglot codebases (Rust, Go, Python, TypeScript/JavaScript, Java, C/C++, Shell, and Markdown docs). Always use this skill instead of running blind recursive `grep -rn` or reading whole files sequentially. --- -## 🎯 When to Use +## πŸ›οΈ The Agentic Triad Architecture (3 Offerings Explained) -1. **Exploring an Unfamiliar Codebase**: When you need to understand the architectural subsystems, packages, or directory relationships without reading hundreds of files. -2. **Locating Exact Symbol Definitions**: Finding functions, structs, classes, or interfaces, their exact line ranges, and signatures without regex text false positives. -3. **Tracing Callers & References**: Finding every function that calls a specific method or imports a package. -4. **Extracting Call Subgraphs**: Pulling a 1-to-3 hop directional call graph slice around a target function directly into your context. -5. **High-Level Conceptual Questions**: Asking "How does X feature work?" and getting a hybrid Graph-RAG answer combining macroscopic summaries with microscopic code slices. +Omni-Graph is architected around a unified high-performance daemon (Rust on `:8080`, SurrealDB v2 on `:8000`, TEI Embeddings on `:8081`) exposed through **three distinct interface tiers**: ---- +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ THE AGENTIC TRIAD β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ 1. NATIVE MCP SERVER β”‚ 2. ERGONOMIC CLI β”‚ 3. REST / CURL API β”‚ +β”‚ (Structured Cognitive) β”‚ (Terminal Hands) β”‚ (Indestructible Floor) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β€’ Zero-token execution β”‚ β€’ Human/Agent friendly β”‚ β€’ Zero runtime dependencies β”‚ +β”‚ β€’ Native IDE function β”‚ β€’ Clean subcommands β”‚ β€’ Universal across any OS/env β”‚ +β”‚ calling (JSON-RPC) β”‚ β€’ Formatted ASCII summaries β”‚ β€’ High-performance direct β”‚ +β”‚ β€’ Schema validated args β”‚ β€’ Auto workspace detection β”‚ JSON streaming β”‚ +β”‚ β€’ No shell escaping β”‚ β€’ Fast terminal debugging β”‚ β€’ Bulletproof fallback β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ OMNI-GRAPH UNIFIED RUST CORE (:8080) β”‚ +β”‚ AST Extraction β€’ SAIR β€’ Topological DAG β€’ Leiden Clustering β€’ PPR Neighborhood β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` -## ⚑ Quick Make Commands (From Repository Root) +### Why 3 Offerings? +Underneath, all three tiers hit the identical Rust HTTP daemon endpoints. However, coding assistants operate in diverse host environments with differing execution permissions: +1. **Tier 1 (Native MCP)**: Ideal for modern IDE agents (Claude Desktop, Cursor, Windsurf, Roo Code, Antigravity IDE) where function calling happens directly in the model context without consuming shell execution tokens. +2. **Tier 2 (Ergonomic CLI `./scripts/omni`)**: Ideal for terminal-driven coding assistants (Aider, CLI agents, or agents with bash execution tools). It automatically resolves workspace context, colors output, formats ASCII tables, and handles command-line flags cleanly. +3. **Tier 3 (Direct Curl / REST API)**: The indestructible bedrock. When running in minimal subshells, sandboxes without `python` or `uv`, or when shell wrapper scripts fail, direct `curl` commands to `http://localhost:8080` guarantee 100% operational continuity. -The easiest way to interact with Omni-Graph is via the root `Makefile`: +--- -```bash -# 1. Discover all indexed codebases / workspaces -make workspaces +## 🚦 Deterministic Execution Decision Tree -# 2. Inspect architectural subsystems (Galaxies) for a workspace -make graph-galaxies PROJECT=session-explorer -make graph-galaxies PROJECT=DSA +When executing an Omni-Graph task, follow this strict decision hierarchy: -# 3. Locate exact symbol definition (LSP textDocument/definition) -make graph-symbol SYM=extractWorkspace PROJECT=session-explorer +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Does your environment expose native β”‚ + β”‚ 'omni_*' tools in its active toolset? β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ YES β”‚ NO + β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ TIER 1: NATIVE MCP β”‚ β”‚ Do you have terminal / bash β”‚ + β”‚ Call 'omni_*' tool call β”‚ β”‚ tool execution access? β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + Fails / β”‚ Error β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β–Ό β”‚ YES β”‚ NO + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β–Ό + β”‚ TIER 2: ERGONOMIC CLI β”‚ β—€β”€β”€β”€β”€β”˜ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Run './scripts/omni' β”‚ β”‚ TIER 3: REST / CURL β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ Run 'curl :8080/api/' β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + Fails / β”‚ Error β”‚ + β–Ό β”‚ Fails / Refused + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ DEGRADED SELF-HEALING PROTOCOL β”‚ + β”‚ Check daemon health ──▢ Spin up stack ──▢ Scoped file read (<150L) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` -# 4. Find all callers of a symbol (LSP textDocument/references) -make graph-references SYM=extractWorkspace PROJECT=session-explorer +--- -# 5. Extract a condensed AST call graph slice (<1500 tokens) -make graph-condense SYM=extractWorkspace PROJECT=session-explorer HOPS=2 +## πŸ—ΊοΈ Master Rosetta Stone: 1-to-1 Equivalence Across All 3 Tiers + +Use this table to translate any codebase reconnaissance intent across MCP, CLI, and REST: + +| Capability / Intent | Tier 1: Native MCP Tool | Tier 2: Ergonomic CLI (`./scripts/omni`) | Tier 3: Low-Level REST / Curl | +| :--- | :--- | :--- | :--- | +| **Symbol Definition** | `omni_definition(symbol="X")` | `./scripts/omni symbol X` | `curl -s "http://localhost:8080/api/symbol?name=X&workspace=PolyTuring"` | +| **Callers & References** | `omni_references(symbol="X")` | `./scripts/omni references X` | `curl -s "http://localhost:8080/api/references?symbol=X&workspace=PolyTuring"` | +| **Condensed Call Slice** | `omni_condense(symbol="X", hops=2)` | `./scripts/omni condense X PolyTuring 2` | `curl -s "http://localhost:8080/api/condense?symbol=X&workspace=PolyTuring&hops=2"` | +| **Semantic Code Search** | `omni_search(query="...", k=10)` | `./scripts/omni search "..." PolyTuring 10` | `curl -s "http://localhost:8080/api/search?q=...&workspace=PolyTuring&k=10"` | +| **Doc Search (Partitioned)**| `omni_search(query="...", include_docs=True)` | `curl` with `include_docs=true` | `curl -s "http://localhost:8080/api/search?q=...&workspace=PolyTuring&include_docs=true"` | +| **Architectural Galaxies** | `omni_galaxies(limit=15)` | `./scripts/omni galaxies` | `curl -s "http://localhost:8080/api/galaxies?workspace=PolyTuring&limit=15"` | +| **Hybrid Graph-RAG Query**| `omni_query(prompt="...")` | `./scripts/omni query "..."` | `curl -s -X POST http://localhost:8080/api/query -H "Content-Type: application/json" -d '{"prompt": "...", "workspace": "PolyTuring"}'` | +| **Augment Runtime Edge** | *(Via CLI or REST)* | `./scripts/omni relate Src Tgt CALLS` | `curl -s -X POST http://localhost:8080/api/relationships -H "Content-Type: application/json" -d '{"source_symbol":"Src","target_symbol":"Tgt","type":"CALLS"}'` | +| **List Workspaces & Stats**| *(Via CLI or REST)* | `./scripts/omni workspaces` | `curl -s "http://localhost:8080/api/workspaces"` | +| **Git Worktrees List/Sync** | *(Via CLI or REST)* | `./scripts/omni worktrees sync` | `curl -s -X POST http://localhost:8080/api/worktrees/sync -H "Content-Type: application/json" -d '{}'` | +| **Watcher Telemetry** | *(Via CLI or REST)* | `./scripts/omni watch status` | `curl -s "http://localhost:8080/api/watch/status"` | +| **Nanometer Fidelity Diagnostics** | *(Via CLI or REST)* | `./scripts/omni watch fidelity` | `curl -s "http://localhost:8080/api/watch/fidelity?workspace=PolyTuring"` | +| **System Health Check** | *(Via CLI or REST)* | `./scripts/omni health` | `curl -s "http://localhost:8080/api/health"` | -# 6. Semantic vector similarity code search -make search-graph Q="session scanner" PROJECT=session-explorer K=5 +--- -# 7. Hybrid Graph-RAG architectural query -make query-graph Q="How does session extraction and date parsing work?" PROJECT=session-explorer +## βš™οΈ Detailed Interface Specifications + +### 1. Tier 1: Native MCP Tools Reference + +The stdio MCP server runs hermetically via `tools/omni-graph/scripts/omni-mcp.py` using `uv run --script`: + +```json +{ + "tools": [ + { + "name": "omni_definition", + "description": "Lookup precise AST definition, signatures, and file line ranges for a code symbol.", + "parameters": { + "symbol": "string (required) β€” Exact identifier name (function, struct, class, interface)", + "workspace": "string (optional) β€” Workspace name (defaults to auto-detected Git root)" + } + }, + { + "name": "omni_references", + "description": "Find all callers, references, and incoming dependency edges across the entire codebase.", + "parameters": { + "symbol": "string (required) β€” Target symbol name", + "workspace": "string (optional) β€” Target workspace name" + } + }, + { + "name": "omni_condense", + "description": "Extract a strictly budgeted (<1500 tokens) multi-hop AST call slice around a symbol using Personalized PageRank.", + "parameters": { + "symbol": "string (required) β€” Root symbol to center call slice around", + "hops": "integer (optional, default 2) β€” Call traversal radius (1 or 2)", + "workspace": "string (optional) β€” Target workspace name" + } + }, + { + "name": "omni_search", + "description": "Perform dense vector semantic search across indexed symbols to locate relevant implementations.", + "parameters": { + "query": "string (required) β€” Natural language or technical concept", + "k": "integer (optional, default 10) β€” Number of top results", + "workspace": "string (optional) β€” Target workspace name", + "include_docs": "boolean (optional, default false) β€” Include markdown documentation nodes" + } + }, + { + "name": "omni_galaxies", + "description": "Inspect macro architectural subsystems (galaxies), modular boundaries, instability scores, and coupling metrics.", + "parameters": { + "workspace": "string (optional) β€” Target workspace name", + "limit": "integer (optional, default 15) β€” Max subsystems to return" + } + }, + { + "name": "omni_query", + "description": "Execute hybrid Graph-RAG retrieval combining vector search, community summaries, and multi-hop AST traces into a grounded Markdown brief.", + "parameters": { + "prompt": "string (required) β€” Architectural question to synthesize", + "workspace": "string (optional) β€” Target workspace name", + "include_docs": "boolean (optional, default false) β€” Include documentation in seeds" + } + } + ] +} ``` ---- - -## πŸ› οΈ CLI Script Commands (`omni.sh`) +### 2. Tier 2: Ergonomic CLI Command Reference -You can also use `./tools/omni-graph/scripts/omni.sh` directly: +The command-line wrapper lives at `./scripts/omni` (symlinked to `tools/omni-graph/scripts/omni.sh`): -### 1. Architectural Subsystem Mapping (`galaxies`) ```bash -./tools/omni-graph/scripts/omni.sh galaxies [workspace] +# Discovery & Health +./scripts/omni health # Verify Rust core, SurrealDB, and TEI container health +./scripts/omni workspaces # Discover all indexed codebases, languages, and node counts +./scripts/omni worktrees [sync] # Scan & synchronize ephemeral Git worktrees + +# AST Code Intelligence +./scripts/omni symbol [ws] # Locate symbol definition, line bounds, and code snippet +./scripts/omni references [ws] # Locate all callers, importing files, and test suites +./scripts/omni condense [ws] [h] # Extract <1500-token PPR-condensed call graph slice (hops: 1 or 2) +./scripts/omni search [ws] [k] # Dense vector semantic code search (top k) +./scripts/omni galaxies [ws] # ASCII table of modular architectural subsystems & coupling metrics +./scripts/omni query [ws] [k] # Hybrid Graph-RAG architectural brief +./scripts/omni relate [t] # Inject dynamic/inferred runtime relationship edge (CALLS, ROUTES_TO) + +# Ingestion & Live Watch +./scripts/omni ingest [ws] # Initial one-time indexing of an untracked repository +./scripts/omni watch status # Inspect real-time file watcher sync metrics & event counters +./scripts/omni watch start [path] # Start live file watcher daemon for repository +./scripts/omni watch stop # Stop live file watcher daemon ``` -Displays an ASCII table of detected Louvain/Leiden modular clusters, dominant file paths, node counts, and key symbol entrypoints. -### 2. Symbol Definition Lookup (`symbol`) -```bash -./tools/omni-graph/scripts/omni.sh symbol "init_pool" [workspace] +### 3. Tier 3: Direct REST API Endpoints Reference + +All endpoints serve JSON directly from the Rust core on `http://localhost:8080`: + +- `GET /api/health` β€” System status (`{"status":"ok","surrealdb":true,"embeddings":true}`) +- `GET /api/workspaces` β€” Array of indexed workspaces, node counts, languages, and live watch states +- `GET /api/symbol?name=&workspace=` β€” Precise symbol definition records +- `GET /api/references?symbol=&workspace=` β€” Callers, importers, and edge categories +- `GET /api/condense?symbol=&workspace=&hops=2` β€” PPR-condensed Markdown call slice +- `GET /api/search?q=&workspace=&k=10&include_docs=false` β€” Vector similarity search +- `GET /api/galaxies?workspace=&limit=15` β€” Louvain/Leiden modular clusters and instability metrics +- `POST /api/query` β€” Hybrid Graph-RAG synthesis (`{"prompt":"...", "workspace":"...", "include_docs":false}`) +- `POST /api/relationships` β€” Edge augmentation (`{"source_symbol":"...", "target_symbol":"...", "type":"..."}`) +- `GET /api/watch/status` β€” Live watcher metrics, event counts, reindexed files, and debouncing status +- `POST /api/watch/start` β€” Enroll directory in live watch (`{"path":"/path/to/repo"}`) +- `POST /api/worktrees/sync` β€” Rescan `.git/worktrees` and enroll child branches + +--- + +## 🧠 Cognitive Intelligence Interpretation: How to Decode & Exploit Responses + +Omni-Graph does not simply return raw textβ€”it produces structured topological intelligence designed to guide your reasoning. Here is how to decode each response payload and make optimal engineering decisions: + +### 1. Decoding `omni_definition` (or `GET /api/symbol`) +Returns an array of matching AST symbols across the workspace: + +```json +{ + "matches": [ + { + "id": "node:`PolyTuring:tools/omni-graph/src/ingestion/mod.rs:execute_ingest:391`", + "file_path": "tools/omni-graph/src/ingestion/mod.rs", + "kind": "function", + "label": "execute_ingest", + "language": "rust", + "line_start": 391, + "line_end": 861, + "text": "async fn execute_ingest( db: &DbClient, embedder: &EmbedderClient... ) { ... }", + "community": 66 + } + ] +} ``` -Returns JSON containing exact file path, start line, end line, AST node kind, and full definition snippet. -### 3. Symbol Caller Lineage (`references`) -```bash -./tools/omni-graph/scripts/omni.sh references "init_pool" [workspace] +* **`line_start` & `line_end` (The 150-Line Gate Bounding Box)**: + * **1-Indexed Inclusive**: Line numbers are exact 1-indexed compiler AST boundaries. + * **Mandatory Action**: Never read the entire file into context. Pass `StartLine: match.line_start` and `EndLine: match.line_end` (or a focused sub-range) to `read_file`. This saves up to 90% of your token window and satisfies the 150-line gate. + * **Chunking Large Symbols (>150 Lines)**: If `line_end - line_start > 150` (e.g., an 800-line pipeline function), DO NOT attempt to read the entire symbol at once. Slice into consecutive 140-line windows (`StartLine: line_start, EndLine: line_start + 140`). + * **Active Line-Shifting Caveat**: When you edit a file, the live watcher updates in ~500ms. If you perform multiple edits in the same turn before live watch syncs, account for line offset delta $\pm\Delta N$. +* **`text` (Code Preview Snippet)**: + * Contains the first ~500 characters of the symbol or file. Inspect this snippet to verify parameter signatures, docstrings, or return types *before* executing any file reads. +* **`kind` (Taxonomy Interpretation)**: + * `function` / `method`: Executable logic. Inspect `line_start` to understand implementation. + * `struct` / `class` / `interface` / `trait`: Data model or public contract. Modifying this alters memory layout or interface signatures. + * `field` / `enum` / `macro`: Sub-symbol structures or metaprogramming constructs. + * `file` (R-063): Discrete file node. `line_start = 1`, `line_end = total_lines` in the file. `text` contains the first 500 characters of file header. + * `directory` (R-063): Spatial container node (`line_start = 0, line_end = 0`). Reveals directory layout without running shell `ls`. + * `workspace`: Top-level workspace root. +* **Querying by File Path or Partial Path**: + * You can query file paths directly: `omni_definition(symbol="src/watcher/mod.rs")` or `omni_definition(symbol="watcher")`. + * Returns both the discrete `file` node and all symbols contained within that path. +* **`matches.len() > 1` (Disambiguation Trigger)**: + * If multiple matches exist, check `file_path` and `language`. + * Common cause: Trait definition in one file, implementation in another, or separate tools sharing a common function name (`new`, `run`, `init`). Always scope your subsequent queries using the matching `file_path`. + +--- + +### 2. Decoding `omni_references` (or `GET /api/references`) +Returns all inbound references, callers, and structural relationships pointing to the target symbol: + +```json +{ + "references": [ + { + "file_path": "tools/omni-graph/src/ingestion/mod.rs", + "label": "new", + "kind": "function", + "type": "CALLS", + "category": "EXTRACTED" + }, + { + "file_path": "tools/omni-graph/tests/unit_tests.rs", + "label": "test_r015_hybrid_filter", + "kind": "function", + "type": "CALLS", + "category": "EXTRACTED" + }, + { + "file_path": "tools/omni-graph/src/ingestion/mod.rs", + "label": "mod.rs", + "kind": "file", + "type": "CONTAINS", + "category": "CONTAINMENT" + } + ] +} ``` -Finds all functions and tests in the graph with directional `CALLS` or `IMPORTS` edges pointing to the target symbol. -### 4. Condensed Multi-Hop Subgraph (`condense`) -```bash -./tools/omni-graph/scripts/omni.sh condense "init_pool" [workspace] 2 +* **The Blast-Radius Risk Matrix**: + * `type: "CALLS"`: **Active Execution Callers**. Modifying the target's parameters, return type, or side effects will break these functions. In v0.7.0+, duplicate calls are deduplicated into distinct caller entities with exact `call_count` and cumulative `weight` (R-104). + * `type: "IMPORTS"`: **Module Dependents**. Renaming or moving the target symbol requires updating import statements in these files. + * `type: "CONTAINS"`: **Parent / Child Containment**. + * Querying a symbol: points up to its enclosing `file` node. + * Querying a file: points down to every declared symbol inside it. + * `type: "CONTAINS_FILE"`: **Directory File Membership**. Points from parent directory to the child file. + * `type: "CONTAINS_DIR"`: **Directory Tree Hierarchy**. Points from parent directory down to child directory. + * `type: "IMPLEMENTS"` / `"EXTENDS"`: **Polymorphic Hierarchy**. Identifies structs or classes inheriting from this interface/base class. +* **Transactional Convergence & Generational Cache (v0.7.0+)**: + * **Zero Torn-Reads (`wait_for_sync=true`)**: MCP and CLI automatically pass `wait_for_sync=true`, awaiting internal live-watcher convergence up to 3,000ms. Endpoints return guaranteed fresh AST ground truth without race conditions during live file edits. + * **Generational Cache Invalidation (`X-Graph-Generation`)**: Every database mutation increments a lock-free 64-bit atomic counter (`X-Graph-Generation`). Inspect this header to detect state mutations without polling. + * **Nanometer Fidelity Diagnostics**: Run `./scripts/omni watch fidelity` or query `GET /api/watch/fidelity?workspace=PolyTuring` to verify 100% topological parity (`fidelity_score: 1.0`, `dangling_directory_edges: 0`). +* **Hierarchical Traversal (Files & Directories)**: + * To list all symbols in a file without reading disk: `omni_references(symbol="src/watcher/mod.rs")` (filters `type: CONTAINS`). + * To inspect directory structure: `omni_references(symbol="watcher")` (reveals parent directory and contained files). +* **Automated Test Suite Discovery**: + * **Critical Pattern**: Filter references where `file_path` contains `test`, `tests/`, `spec`, or `_test.go`. + * **Mandatory Protocol**: These are the exact regression tests you must run after making changes to verify zero regressions! + +--- + +### 3. Decoding `omni_condense` (or `GET /api/condense`) +Extracts a personalized PageRank (PPR) condensed neighborhood slice guaranteed under `<1,490 tokens`. + +* **`direct_callers`**: Inbound execution triggers. Answers: *"Who invokes this component?"* +* **`direct_callees`**: Outbound dependencies and delegated workers. Answers: *"What services and helpers does this component rely on to do its job?"* +* **`related_files`**: The tightly coupled cluster of files involved in this feature. +* **`formatted_markdown` (Execution Flow Analysis)**: + * Gives you a pre-digested view of function signatures, caller $\to$ target $\to$ callee edges, and code snippets. + * **Cognitive Decision**: When investigating an unfamiliar bug or workflow, call `omni_condense` first. It replaces reading 5-10 separate files across multiple directories with a single, prompt-safe trace. + +--- + +### 4. Decoding `omni_galaxies` (or `GET /api/galaxies`) +Returns the top modular subsystems discovered via Louvain/Leiden label propagation clustering: + +```json +{ + "galaxies": [ + { + "name": "tools/omni-graph/src/db (mod.rs)", + "dominant_path": "tools/omni-graph/src/db", + "node_count": 156, + "afferent_coupling": 61, + "efferent_coupling": 44, + "instability": 0.419, + "role": "Domain Service", + "sample_symbols": ["DbClient", "store_nodes", "store_edges", "purge_workspace"] + } + ] +} ``` -Outputs a dense, beautifully formatted Markdown slice with definitions, signatures, and ASCII call graph traces ready to paste into your reasoning context. -### 5. Semantic Vector Search (`search`) -```bash -./tools/omni-graph/scripts/omni.sh search "websocket message dispatcher" [workspace] 5 +* **Afferent Coupling ($C_a$)**: Number of incoming dependencies from outside the galaxy. + * High $C_a$ = High centrality. Many other subsystems depend on this module. +* **Efferent Coupling ($C_e$)**: Number of outgoing dependencies to outside the galaxy. + * High $C_e$ = High coordination. This module delegates work out to other modules. +* **Instability Index ($I = \frac{C_e}{C_a + C_e}$, range 0.0 to 1.0)**: + * **$I \to 0.0$ (Extremely Stable Core)**: Foundational services (e.g. `src/db`). Modifying these has a massive blast radius across the entire repo. Exercise maximum caution and verify all tests. + * **$0.3 \le I \le 0.7$ (Balanced Domain Services)**: Business logic, parsers, and pipeline workers (e.g. `src/ingestion`, `src/api`). + * **$I \to 1.0$ (Volatile Leaf / Orchestrator)**: CLI entrypoints, UI components, test runners. Easy to modify; changes are isolated with minimal ripple effect on core systems. +* **Abstractness ($A = \frac{N_{\text{abstract}}}{N_{\text{total}}}$, range 0.0 to 1.0)**: + * Ratio of interfaces, traits, and abstract classes to total symbols in the galaxy. +* **Distance from Main Sequence ($D = |A + I - 1|$, range 0.0 to 1.0)**: + * **$D \to 0.0$ (Optimal Architectural Balance)**: Follows Clean Architecture. Highly abstract modules are stable; concrete modules are flexible. + * **$D \gg 0.5$ with $A \to 0, I \to 0$ (Zone of Pain)**: Brittle concrete foundation that everything depends on. + * **$D \gg 0.5$ with $A \to 1, I \to 1$ (Zone of Uselessness)**: Unimplemented abstractions that nobody depends on. +* **Scale-Adaptive Cosmology ($K_{\text{adaptive}}$)**: + * Galaxies scale sub-linearly with graph complexity $N$: $K = \text{clamp}(\lfloor 3.5 \cdot N^{0.35} \rfloor, 5, 150)$ with Affinity-Floor Invariant (zero forced merges of decoupled systems). +* **`dominant_path` & `sample_symbols`**: + * Tells you where the subsystem lives on disk and what its 3-5 central hub symbols are. If tasked with exploring a new area, begin with the hub symbols. + +--- + +### 5. Decoding `omni_search` vs `omni_query` +* **When to use `omni_search` (Precision Pinpoint)**: + * Use when you need to locate specific functions, structs, or files by conceptual name (e.g., `"fifo queue worker"`, `"jwt verification"`). + * Check the top 3-5 results, note the `file_path`, and transition immediately to `omni_definition` or `omni_condense`. + * Set `include_docs: true` ONLY when searching user guides, RFCs, or markdown devlogs. +* **When to use `omni_query` (Architectural Synthesis)**: + * Use when asking high-level structural questions: *"How does Omni-Graph handle file watcher debouncing and error recovery?"* + * It executes hybrid Graph-RAG (vector seeds + community summaries + AST graph links) to produce a synthesized Markdown brief. + * Do NOT use `omni_query` when you only need a file path or line numberβ€”use `omni_search` or `omni_definition` instead. + +--- + +### 6. The 5-Step Autonomous Agent Reconnaissance Ladder + +Whenever approaching an unfamiliar codebase or solving a non-trivial issue, execute this cognitive ladder: + ``` -Performs 384-dimensional cosine ANN vector search across SurrealDB HNSW index. +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ THE 5-STEP AGENT RECONNAISSANCE LADDER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Step β”‚ Action β”‚ Tool / Command β”‚ Cognitive Objective β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ 1. β”‚ Subsystem Identification β”‚ `omni_galaxies()` β”‚ Identify owning domainβ”‚ +β”‚ β”‚ β”‚ β”‚ & instability risk β”‚ +β”‚ 2. β”‚ Symbol Pinpointing β”‚ `omni_definition(symbol)` β”‚ Acquire exact path β”‚ +β”‚ β”‚ β”‚ β”‚ & line bounds β”‚ +β”‚ 3. β”‚ Execution Flow Tracing β”‚ `omni_condense(symbol)` β”‚ Trace callers/callees β”‚ +β”‚ β”‚ β”‚ β”‚ in <1,490 tokens β”‚ +β”‚ 4. β”‚ Blast-Radius & Test Auditβ”‚ `omni_references(symbol)` β”‚ Identify dependents β”‚ +β”‚ β”‚ β”‚ β”‚ & test suites β”‚ +β”‚ 5. β”‚ Surgical Bounded Action β”‚ `read_file(start, end)` β”‚ Inspect bounded slice β”‚ +β”‚ β”‚ β”‚ β”‚ & execute change β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 🧩 Resolving Permutations, Combinations & Scoping + +### 1. Workspace Scoping Permutations +- **Auto-Detection (Default)**: In both MCP and CLI, omitting `workspace` automatically resolves the current Git repository name (`git rev-parse --show-toplevel`). +- **Explicit Scoping**: When working in a multi-repo monorepo or inspecting dependencies in an indexed sibling workspace, pass `workspace="TargetRepo"`: + - MCP: `omni_definition(symbol="UserHandler", workspace="session-explorer")` + - CLI: `./scripts/omni symbol UserHandler session-explorer` + - REST: `curl -s "http://localhost:8080/api/symbol?name=UserHandler&workspace=session-explorer"` +- **Unscoped Monorepo Scan (Divergence Check)**: Omit `workspace` on REST `/api/symbol?name=X` to view matches across ALL indexed repositories side-by-side. + +### 2. Content Partitioning: Code vs Documentation +Omni-Graph v0.3.0 enforces strict Content Partitioning to prevent Markdown documentation from shadowing source code: +- By default, all vector queries (`omni_search`, `omni_query`, `/api/search`) search **code symbols only** (`include_docs: false`). +- To search architectural guides, specifications, and living documentation, explicitly enable documentation search: + - MCP: `omni_search(query="how to deploy", include_docs=True)` + - CLI/REST: `curl -s "http://localhost:8080/api/search?q=how+to+deploy&workspace=PolyTuring&include_docs=true"` + +### 3. Hop Radius & Context Budgeting +- Default traversal is `hops=2`, covering caller $\to$ root $\to$ callee. +- If investigating an ultra-dense central hub function with dozens of dependencies, pass `hops=1` for a tighter, atomic call view. +- Subgraph condensation automatically executes 25-step **Personalized PageRank (PPR)** ($\alpha=0.85$) and strictly truncates output at 1,490 tokens to guarantee prompt safety. -### 6. Hybrid Graph-RAG Retrieval (`query`) +--- + +## πŸ› οΈ Degraded & Out-of-Order Self-Healing Playbook + +When operating in real environments, things may not always be in order. Follow these deterministic recovery protocols: + +### Scenario 1: MCP Tool Not Present in Model Context +- **Symptom**: Model environment does not list `omni_*` tools in its tool catalog. +- **Root Cause**: IDE does not support MCP, or MCP server is not registered in client configuration. +- **Recovery Protocol**: + 1. **DO NOT** attempt to guess or hallucinate MCP tool names. + 2. Switch immediately to **Tier 2 Ergonomic CLI**: execute commands via `./scripts/omni `. + 3. If your agent framework has no shell tool, use **Tier 3 Curl** via whatever HTTP client is available. + +### Scenario 2: CLI Permission Denied or File Not Found +- **Symptom**: Shell execution returns `./scripts/omni: Permission denied` or `No such file or directory`. +- **Recovery Protocol**: + 1. Verify execution path: run `ls -la scripts/omni` from repository root. + 2. If missing executable bit: run `chmod +x ./scripts/omni tools/omni-graph/scripts/*.sh`. + 3. If current working directory is a subfolder, use absolute path: `${REPO_ROOT}/scripts/omni` or fallback to **Tier 3 Curl**. + +### Scenario 3: Daemon Down or Connection Refused (`localhost:8080`) +- **Symptom**: `curl` or CLI returns `Failed to connect to localhost port 8080: Connection refused`. +- **Recovery Protocol**: + 1. Check Docker container status: + ```bash + docker ps --filter "name=omni" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" + ``` + 2. If containers are stopped, spin up the stack from repo root: + ```bash + make up + # or: docker compose -f tools/omni-graph/docker-compose.yml up -d + ``` + 3. Wait 5 seconds for health status: `curl -s http://localhost:8080/api/health`. + 4. **Cold Fallback (If Docker is completely unavailable)**: + - DO NOT crash or enter an infinite loop. + - Switch to **Cold Graceful Degradation**: locate files using `git ls-files` and inspect focused file slices using `view_file` strictly respecting the **150-line gate** (`StartLine: X, EndLine: X+140`). + +### Scenario 4: Workspace Not Indexed or Total Nodes is Zero +- **Symptom**: Query returns `total_results: 0` or workspace name is not found. +- **Recovery Protocol**: + 1. Check registered workspaces: + ```bash + ./scripts/omni workspaces + ``` + 2. Verify if the repository is registered under a slightly different name (e.g., casing or subfolder name). + 3. If the repository is completely unindexed, run one-time ingestion: + ```bash + ./scripts/omni ingest . [workspace_name] + ``` + 4. Wait for ingestion confirmation (`ingestion_time_ms`), then resume querying. + +### Scenario 5: Symbol Lookup Returns 0 Matches +- **Symptom**: `omni_definition(symbol="processOrder")` returns empty matches. +- **Root Causes**: + - Spelling, case conventions (snake_case vs camelCase vs PascalCase), or language differences. + - Target symbol is an unexported local variable or anonymous closure. + - Symbol is part of an external third-party library or vendor crate. +- **Recovery Protocol**: + 1. Fall back to Dense Vector Semantic Search: + ```bash + ./scripts/omni search "process order" [workspace] 5 + ``` + 2. Query architectural galaxies to locate the owning module: + ```bash + ./scripts/omni galaxies [workspace] + ``` + 3. If external library, query the caller function that imports it to view the usage pattern. + +### Scenario 6: Symbol Ambiguity (Multiple Matches Across Files) +- **Symptom**: `omni_definition(symbol="validate")` returns 6 matches across multiple files. +- **Recovery Protocol**: + 1. Inspect the returned JSON array: each match includes `file_path`, `language`, and `kind`. + 2. Filter by the specific file path or language you are targeting. + 3. For callers/references, query with workspace scoping or inspect the caller's `source_file` to isolate the exact dependency graph. + +### Scenario 7: Condensed Subgraph Too Large / Budget Exceeded +- **Symptom**: Target function is a massive utility hub; 2-hop trace is dense. +- **Recovery Protocol**: + 1. Omni-Graph v0.3.0 automatically applies Personalized PageRank (PPR) power iteration ($\alpha=0.85$, 25 iterations) and caps output at 1,490 tokens. + 2. If a more focused trace is desired, dial down hops to `hops=1`: + - MCP: `omni_condense(symbol="X", hops=1)` + - CLI: `./scripts/omni condense X PolyTuring 1` + +### Scenario 8: Live Watch Telemetry Desynchronized +- **Symptom**: You edited a file, but AST queries still report old line numbers after 1 second. +- **Recovery Protocol**: + 1. Check live watch status: + ```bash + ./scripts/omni watch status + ``` + 2. If status is `stopped` or `inactive`, restart the watcher: + ```bash + ./scripts/omni watch start . + ``` + 3. The watcher automatically debounces (500ms) and re-indexes modified files with zero full-table resets. + +### Scenario 9: Operating in Isolated Git Worktrees +- **Symptom**: Agent is running inside a Git worktree (`git worktree add ../wt-feature`). +- **Recovery Protocol**: + 1. Sync worktrees: + ```bash + ./scripts/omni worktrees sync + ``` + 2. Omni-Graph resolves the `.git` pointer, inherits cluster seeds from the parent workspace, and starts live watching the worktree. + 3. Scope all queries using `workspace=` to prevent cross-branch AST edge bleeding. + +--- + +## πŸ”Œ Client Installation & Setup Guide + +To install and register the Omni-Graph skill and MCP server in your coding environment: + +### 1. Antigravity CLI / IDE +Run the canonical automated installer: ```bash -./tools/omni-graph/scripts/omni.sh query "How does authentication flow work?" [workspace] 5 +# Workspace installation (.agents/) +make setup-agent + +# Or global system installation (~/.gemini/config/) +make setup-agent global ``` -Combines microscopic vector seeds with macroscopic Louvain community cluster summaries and expanded AST subgraphs. ---- +### 2. Claude Desktop +Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): +```json +{ + "mcpServers": { + "omni-graph": { + "command": "uv", + "args": [ + "run", + "--script", + "/absolute/path/to/PolyTuring/tools/omni-graph/scripts/omni-mcp.py" + ], + "env": { + "OMNI_API_URL": "http://localhost:8080" + } + } + } +} +``` -## 🌐 Direct HTTP REST API (`http://localhost:8080`) +### 3. Cursor +Add to your project's `.cursor/mcp.json`: +```json +{ + "mcpServers": { + "omni-graph": { + "command": "uv", + "args": [ + "run", + "--script", + "${workspaceFolder}/tools/omni-graph/scripts/omni-mcp.py" + ] + } + } +} +``` -For automated subagents, direct REST queries are available: +### 4. Windsurf / Codeium +Add to `~/.codeium/windsurf/mcp_config.json`: +```json +{ + "mcpServers": { + "omni-graph": { + "command": "uv", + "args": [ + "run", + "--script", + "/absolute/path/to/PolyTuring/tools/omni-graph/scripts/omni-mcp.py" + ] + } + } +} +``` -- `GET /api/workspaces` β€” List all indexed codebases -- `GET /api/galaxies?workspace=` β€” List architectural clusters -- `GET /api/symbol?name=&workspace=` β€” Symbol definition -- `GET /api/references?symbol=&workspace=` β€” Symbol callers -- `GET /api/condense?symbol=&workspace=&hops=2` β€” Condensed markdown slice -- `GET /api/search?q=&workspace=&k=10` β€” Vector search -- `POST /api/query` (`{"prompt": "...", "workspace": "..."}`) β€” Graph-RAG query +### 5. Aider / Standalone Terminal Coding Assistants +Aider and terminal agents execute commands directly via the `./scripts/omni` CLI: +```bash +# Add to .aider.conf.yml or run in chat: +/run ./scripts/omni symbol +/run ./scripts/omni condense +``` --- ## πŸ“‹ Recommended Agent Workflow Recipes ### Recipe A: Investigating a Bug in an Unfamiliar Module -1. Run `make workspaces` to confirm the workspace name (e.g. `session-explorer`). -2. Run `make graph-galaxies PROJECT=session-explorer` to find which subsystem owns the feature. -3. Run `make search-graph Q="" PROJECT=session-explorer` to get the entrypoint symbol. -4. Run `make graph-condense SYM= PROJECT=session-explorer HOPS=2` to understand the full call trace. -5. Only now open the specific target file via `view_file` at the exact line range to write your fix. - -### Recipe B: Refactoring or Renaming a Function -1. Run `make graph-symbol SYM=` to inspect its current implementation and line range. -2. Run `make graph-references SYM=` to get a complete, guaranteed list of all caller locations and test files that depend on it. -3. Edit the definition and all callers with targeted changes, ensuring zero broken dependencies. +1. Discover the owning subsystem without reading files: + - MCP: `omni_galaxies()` + - CLI: `./scripts/omni galaxies` +2. Search for the error message or feature concept: + - MCP: `omni_search(query="rate limiter token refill", k=5)` + - CLI: `./scripts/omni search "rate limiter token refill"` +3. Pull a condensed AST call graph slice (<1500 tokens) around the entrypoint: + - MCP: `omni_condense(symbol="refill_tokens", hops=2)` + - CLI: `./scripts/omni condense refill_tokens PolyTuring 2` +4. Only now open the specific target file via `view_file` at the exact line range to write your fix. + +### Recipe B: Safe Refactoring or Renaming a Public Symbol +1. Inspect current definition and signature: + - MCP: `omni_definition(symbol="calculate_tax")` + - CLI: `./scripts/omni symbol calculate_tax` +2. **Mandatory Blast-Radius Check**: Locate all callers and importing files across the repository: + - MCP: `omni_references(symbol="calculate_tax")` + - CLI: `./scripts/omni references calculate_tax` +3. Edit the definition and all callers with surgical precision, ensuring zero broken dependencies. + +### Recipe C: Augmenting Dynamic Cross-Service Dependencies +When inspecting Dockerfiles, HTTP routing tables, or message brokers, Tree-sitter cannot infer runtime connections: +1. Identify source and target components (e.g. `FrontendClient` $\to$ `OrderServiceAPI`). +2. Inject an inferred relationship edge: + - CLI: `./scripts/omni relate FrontendClient OrderServiceAPI ROUTES_TO` + - REST: `POST /api/relationships` with `{"source_symbol":"FrontendClient", "target_symbol":"OrderServiceAPI", "type":"ROUTES_TO", "category":"INFERRED"}` +3. All future blast-radius queries (`omni_references`) will immediately track this cross-service dependency. diff --git a/.agents/skills/omni-graph/scripts/omni-mcp.py b/.agents/skills/omni-graph/scripts/omni-mcp.py new file mode 100755 index 0000000..ca74127 --- /dev/null +++ b/.agents/skills/omni-graph/scripts/omni-mcp.py @@ -0,0 +1,447 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.10" +# dependencies = [] +# /// +""" +omni-mcp.py β€” Native Model Context Protocol (MCP) stdio server for Omni-Graph. +Implements: R-070, R-078 (JSON-RPC 2.0 stdio protocol 2024-11-05). + +Provides structured zero-token shell-free AST queries for AI coding assistants: +- omni_definition: Lookup precise AST definition and metadata +- omni_references: Find all callers and incoming dependency edges +- omni_condense: Extract multi-hop call trace slice (<1500 tokens) +- omni_search: Dense vector semantic search across code symbols +- omni_galaxies: Inspect architectural subsystems and coupling metrics +- omni_query: Execute hybrid Graph-RAG retrieval (seeds + AST + community) +""" + +import sys +import os +import json +import urllib.request +import urllib.parse +import subprocess + +API_URL = os.environ.get("OMNI_API_URL", "http://localhost:8080") + +def get_default_workspace() -> str: + env_ws = os.environ.get("OMNI_WORKSPACE") + if env_ws: + return env_ws.rstrip("/").split("/")[-1] + try: + git_root = subprocess.check_output( + ["git", "rev-parse", "--show-toplevel"], + stderr=subprocess.DEVNULL, + text=True + ).strip() + if git_root: + return os.path.basename(git_root) + except Exception: + pass + return os.path.basename(os.getcwd()) + +TOOLS_SPEC = [ + { + "name": "omni_definition", + "description": "Lookup precise AST definition, signatures, and file line ranges for a code symbol. Essential before editing code.", + "inputSchema": { + "type": "object", + "properties": { + "symbol": { + "type": "string", + "description": "The exact identifier name of the function, struct, class, method, or interface." + }, + "workspace": { + "type": "string", + "description": "Target workspace name (defaults to current project root)." + } + }, + "required": ["symbol"] + } + }, + { + "name": "omni_references", + "description": "Find all callers, references, and incoming dependency edges for a symbol across the entire codebase.", + "inputSchema": { + "type": "object", + "properties": { + "symbol": { + "type": "string", + "description": "The target symbol name to find references for." + }, + "workspace": { + "type": "string", + "description": "Target workspace name (defaults to current project root)." + } + }, + "required": ["symbol"] + } + }, + { + "name": "omni_condense", + "description": "Extract a strictly budgeted (<1500 tokens) multi-hop AST call slice around a symbol. Contains full function signatures, callers, callees, and dependency edges without reading thousands of file lines.", + "inputSchema": { + "type": "object", + "properties": { + "symbol": { + "type": "string", + "description": "Root symbol to center the call slice around." + }, + "hops": { + "type": "integer", + "description": "Call graph traversal radius (1 or 2 hops, default 2)." + }, + "workspace": { + "type": "string", + "description": "Target workspace name (defaults to current project root)." + } + }, + "required": ["symbol"] + } + }, + { + "name": "omni_search", + "description": "Perform dense vector semantic search across indexed code symbols to locate relevant files and implementations.", + "inputSchema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Natural language or technical question/search query." + }, + "k": { + "type": "integer", + "description": "Number of top results to return (default 10)." + }, + "workspace": { + "type": "string", + "description": "Target workspace name (defaults to current project root)." + }, + "include_docs": { + "type": "boolean", + "description": "Whether to include markdown documentation nodes (default false: code-only)." + } + }, + "required": ["query"] + } + }, + { + "name": "omni_galaxies", + "description": "Inspect macro architectural subsystems (galaxies), modular boundaries, instability scores, and cross-subsystem coupling metrics.", + "inputSchema": { + "type": "object", + "properties": { + "workspace": { + "type": "string", + "description": "Target workspace name (defaults to current project root)." + }, + "limit": { + "type": "integer", + "description": "Maximum number of subsystems to return (default 15)." + } + } + } + }, + { + "name": "omni_query", + "description": "Execute hybrid Graph-RAG retrieval combining vector search, community summaries, and multi-hop AST traces into a grounded Markdown brief.", + "inputSchema": { + "type": "object", + "properties": { + "prompt": { + "type": "string", + "description": "Architectural or implementation question to synthesize." + }, + "workspace": { + "type": "string", + "description": "Target workspace name (defaults to current project root)." + }, + "top_k": { + "type": "integer", + "description": "Number of top AST seed hits (default 5)." + }, + "include_docs": { + "type": "boolean", + "description": "Whether to include documentation in search seeds (default false: code-only)." + } + }, + "required": ["prompt"] + } + } +] + +def make_http_request(url: str, data: dict = None, timeout: int = 15): + headers = {"Content-Type": "application/json"} + body = json.dumps(data).encode("utf-8") if data is not None else None + req = urllib.request.Request(url, data=body, headers=headers) + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + return json.loads(resp.read().decode("utf-8")) + except urllib.error.HTTPError as e: + if e.code == 423: + try: + err_data = json.loads(e.read().decode("utf-8")) + return { + "error": "HTTP 423 Locked", + "message": err_data.get("message", "Workspace is actively synchronizing graph topology."), + "locked": True, + } + except Exception: + return { + "error": "HTTP 423 Locked", + "message": "Workspace is actively synchronizing graph topology. Please retry in a moment.", + "locked": True, + } + raise + +def handle_tool_call(name: str, args: dict) -> dict: + workspace = args.get("workspace") or get_default_workspace() + + try: + if name == "omni_definition": + symbol = args["symbol"] + params = urllib.parse.urlencode({"name": symbol, "workspace": workspace, "wait_for_sync": "true"}) + res = make_http_request(f"{API_URL}/api/symbol?{params}") + if res.get("locked"): + return {"content": [{"type": "text", "text": f"⏳ Workspace '{workspace}' is synchronizing graph topology. {res.get('message', '')}"}]} + matches = res.get("matches", []) + if not matches: + return {"content": [{"type": "text", "text": f"Symbol '{symbol}' not found in workspace '{workspace}'."}]} + + lines = [f"Found {len(matches)} match(es) for '{symbol}' in workspace '{workspace}':\n"] + for m in matches: + lines.append(f"β€’ [{m.get('kind', 'symbol')}] `{m.get('label')}` in `{m.get('file_path')}:{m.get('line_start')}-{m.get('line_end')}` ({m.get('language')})") + text_preview = m.get('text', '').strip() + if text_preview: + lines.append(f" ```{m.get('language', '')}\n {text_preview[:400]}\n ```") + return {"content": [{"type": "text", "text": "\n".join(lines)}]} + + elif name == "omni_references": + symbol = args["symbol"] + params = urllib.parse.urlencode({"symbol": symbol, "workspace": workspace, "wait_for_sync": "true"}) + res = make_http_request(f"{API_URL}/api/references?{params}") + if res.get("locked"): + return {"content": [{"type": "text", "text": f"⏳ Workspace '{workspace}' is synchronizing graph topology. {res.get('message', '')}"}]} + raw_refs = res.get("references", []) + # Also check legacy callers/importers as fallback if present + if not raw_refs and ("callers" in res or "importers" in res): + raw_refs = res.get("callers", []) + res.get("importers", []) + + total = len(raw_refs) + if total == 0: + return {"content": [{"type": "text", "text": f"No incoming references found for '{symbol}' in workspace '{workspace}'."}]} + + lines = [f"Total References for '{symbol}' ({total}):\n"] + + callers = [] + containment = [] + doc_refs = [] + inheritance = [] + others = [] + + for ref in raw_refs: + edge_type = ref.get("type", "CALLS") + label = ref.get("label", ref.get("source_symbol", "unknown")) + file_path = ref.get("file_path", ref.get("source_file", "")) + line_start = ref.get("line_start", 0) + kind = ref.get("kind", "") + loc = f"`{file_path}:{line_start}`" if line_start else f"`{file_path}`" + entry = f" ← `{label}` ({kind}) in {loc} [{edge_type}]" if kind else f" ← `{label}` in {loc} [{edge_type}]" + + if edge_type == "CALLS": + callers.append(entry) + elif edge_type in ("CONTAINS", "CONTAINS_FILE", "CONTAINS_DIR"): + containment.append(entry) + elif edge_type == "REFERENCES" or ref.get("language") == "markdown": + doc_refs.append(entry) + elif edge_type in ("IMPLEMENTS", "EXTENDS"): + inheritance.append(entry) + else: + others.append(entry) + + if callers: + lines.append(f"Direct Callers ({len(callers)}):") + lines.extend(callers[:20]) + if inheritance: + lines.append(f"\nInheritance & Interfaces ({len(inheritance)}):") + lines.extend(inheritance[:15]) + if containment: + lines.append(f"\nContainment & Hierarchy ({len(containment)}):") + lines.extend(containment[:15]) + if doc_refs: + lines.append(f"\nDocument References ({len(doc_refs)}):") + lines.extend(doc_refs[:10]) + if others: + lines.append(f"\nOther References ({len(others)}):") + lines.extend(others[:15]) + + return {"content": [{"type": "text", "text": "\n".join(lines)}]} + + elif name == "omni_condense": + symbol = args["symbol"] + hops = args.get("hops", 2) + params = urllib.parse.urlencode({"symbol": symbol, "workspace": workspace, "hops": hops, "wait_for_sync": "true"}) + res = make_http_request(f"{API_URL}/api/condense?{params}") + if res.get("locked"): + return {"content": [{"type": "text", "text": f"⏳ Workspace '{workspace}' is synchronizing graph topology. {res.get('message', '')}"}]} + formatted_md = res.get("formatted_markdown", "") + tokens = res.get("token_estimate", 0) + text = f"{formatted_md}\n\n*(Token estimate: ~{tokens} tokens)*" + return {"content": [{"type": "text", "text": text}]} + + elif name == "omni_search": + query = args["query"] + k = args.get("k", 10) + include_docs = "true" if args.get("include_docs", False) else "false" + params = urllib.parse.urlencode({"q": query, "workspace": workspace, "k": k, "include_docs": include_docs, "wait_for_sync": "true"}) + res = make_http_request(f"{API_URL}/api/search?{params}") + if isinstance(res, dict) and res.get("locked"): + return {"content": [{"type": "text", "text": f"⏳ Workspace '{workspace}' is synchronizing graph topology. {res.get('message', '')}"}]} + hits = res.get("results", []) if isinstance(res, dict) else res + if not hits: + return {"content": [{"type": "text", "text": f"No matches found for query: '{query}'"}]} + + lines = [f"Semantic search results for '{query}' (top {len(hits)}):\n"] + for hit in hits: + sim = hit.get("similarity", 0.0) + lines.append(f"β€’ `{hit.get('label')}` ({hit.get('kind')}) in `{hit.get('file_path')}:{hit.get('line_start')}` [cos: {sim:.3f}]") + sig = hit.get("text", "").splitlines() + first_line = sig[0].strip() if sig else "" + if first_line: + lines.append(f" Signature: `{first_line[:120]}`") + return {"content": [{"type": "text", "text": "\n".join(lines)}]} + + elif name == "omni_galaxies": + limit = args.get("limit", 15) + params = urllib.parse.urlencode({"workspace": workspace, "limit": limit, "wait_for_sync": "true"}) + res = make_http_request(f"{API_URL}/api/galaxies?{params}") + if res.get("locked"): + return {"content": [{"type": "text", "text": f"⏳ Workspace '{workspace}' is synchronizing graph topology. {res.get('message', '')}"}]} + galaxies = res.get("galaxies", []) + total = res.get("total_galaxies", len(galaxies)) + + lines = [f"Architectural Galaxies for '{workspace}' (showing {len(galaxies)} of {total}):\n"] + for g in galaxies: + role = g.get("role", "Service") + nodes = g.get("node_count", 0) + ca = g.get("afferent_coupling", 0) + ce = g.get("efferent_coupling", 0) + inst = g.get("instability", 0.0) + lines.append(f"🌌 **{g.get('name')}** [{role}] β€” {nodes} nodes | Ca: {ca}, Ce: {ce}, Instability: {inst:.2f}") + syms = g.get("sample_symbols", []) + if syms: + lines.append(f" Key symbols: {', '.join(syms[:6])}") + return {"content": [{"type": "text", "text": "\n".join(lines)}]} + + elif name == "omni_query": + prompt = args["prompt"] + include_docs = args.get("include_docs", False) + top_k = args.get("top_k", 5) + payload = {"prompt": prompt, "workspace": workspace, "include_docs": include_docs, "top_k": top_k, "wait_for_sync": True} + res = make_http_request(f"{API_URL}/api/query", data=payload) + if res.get("locked"): + return {"content": [{"type": "text", "text": f"⏳ Workspace '{workspace}' is synchronizing graph topology. {res.get('message', '')}"}]} + macro = res.get("macroscopic_summary", "") + subgraph = res.get("expanded_subgraph", "") + return {"content": [{"type": "text", "text": f"{macro}\n\n{subgraph}"}]} + + else: + return {"isError": True, "content": [{"type": "text", "text": f"Unknown tool: '{name}'"}]} + + except urllib.error.URLError as e: + return { + "isError": True, + "content": [ + { + "type": "text", + "text": f"Omni-Graph API connection error ({API_URL}): {e.reason}. Ensure Omni-Graph is running (`make omni-graph`)." + } + ] + } + except Exception as e: + return {"isError": True, "content": [{"type": "text", "text": f"Tool execution failed: {str(e)}"}]} + +def main(): + while True: + line = sys.stdin.readline() + if not line: + break + line = line.strip() + if not line: + continue + + try: + req = json.loads(line) + except Exception: + continue + + msg_id = req.get("id") + method = req.get("method") + params = req.get("params", {}) + + if method == "initialize": + res = { + "jsonrpc": "2.0", + "id": msg_id, + "result": { + "protocolVersion": "2024-11-05", + "capabilities": { + "tools": {} + }, + "serverInfo": { + "name": "omni-graph-mcp", + "version": "0.3.0" + } + } + } + sys.stdout.write(json.dumps(res) + "\n") + sys.stdout.flush() + + elif method == "notifications/initialized": + # No-op acknowledgement + pass + + elif method == "tools/list": + res = { + "jsonrpc": "2.0", + "id": msg_id, + "result": { + "tools": TOOLS_SPEC + } + } + sys.stdout.write(json.dumps(res) + "\n") + sys.stdout.flush() + + elif method == "tools/call": + tool_name = params.get("name", "") + tool_args = params.get("arguments", {}) + call_res = handle_tool_call(tool_name, tool_args) + res = { + "jsonrpc": "2.0", + "id": msg_id, + "result": call_res + } + sys.stdout.write(json.dumps(res) + "\n") + sys.stdout.flush() + + elif method == "ping": + res = {"jsonrpc": "2.0", "id": msg_id, "result": {}} + sys.stdout.write(json.dumps(res) + "\n") + sys.stdout.flush() + + else: + if msg_id is not None: + res = { + "jsonrpc": "2.0", + "id": msg_id, + "error": { + "code": -32601, + "message": f"Method not found: {method}" + } + } + sys.stdout.write(json.dumps(res) + "\n") + sys.stdout.flush() + +if __name__ == "__main__": + main() diff --git a/.agents/skills/omni-graph/scripts/omni.sh b/.agents/skills/omni-graph/scripts/omni.sh index a8c2fb3..c5e2f22 100755 --- a/.agents/skills/omni-graph/scripts/omni.sh +++ b/.agents/skills/omni-graph/scripts/omni.sh @@ -19,14 +19,17 @@ Usage: omni.sh [args...] Commands: health Check service health (Rust API, SurrealDB, TEI) workspaces List all indexed codebases/workspaces and stats + worktrees [sync [ws]] List or sync git worktrees across parent codebases search [ws] [k] Vector similarity search (optional workspace filter) symbol [ws] Symbol definition lookup (LSP definition) references [ws] Find all callers/references (LSP references) + relate [t] [ws] Augment graph with dynamic/inferred relationship condense [ws] [hops] Multi-hop AST subgraph slice (<1500 tokens for agents) query [ws] [k] Hybrid Graph-RAG retrieval (seeds + AST + community) cluster [workspace] Run Louvain/Leiden community detection clustering galaxies [workspace] Inspect architectural galaxy subsystems ingest [project] Index a codebase/directory into SurrealDB + watch Dynamic live delta sync, watching & fidelity diagnostics stats Show aggregated graph stats EOF exit 1 @@ -69,11 +72,30 @@ try: langs = ', '.join(item.get('languages', [])) files = len(item.get('files', [])) print(f'{ws:<25} {nodes:<15} {langs:<20} {files:<10}') + for wt in item.get('worktrees', []): + wt_name = wt.get('workspace', '') + wt_branch = wt.get('branch', '') + wt_nodes = wt.get('total_nodes', 0) + print(f' └── 🌿 {wt_branch:<21} ({wt_name}) {wt_nodes:,} nodes') except Exception as e: print(f'Error connecting to Omni-Graph API: {e}') " ;; + worktrees) + ACTION="${1:-list}" + if [ "$ACTION" = "sync" ]; then + WS="$(norm_ws "${2:-}")" + PAYLOAD="{}" + if [ -n "$WS" ]; then + PAYLOAD="{\"workspace\": \"$WS\"}" + fi + curl -sf -X POST "${ENDPOINT}/api/worktrees/sync" -H "Content-Type: application/json" -d "$PAYLOAD" | python3 -m json.tool 2>/dev/null || curl -s -X POST "${ENDPOINT}/api/worktrees/sync" -H "Content-Type: application/json" -d "$PAYLOAD" + else + curl -sf "${ENDPOINT}/api/worktrees" | python3 -m json.tool 2>/dev/null || curl -s "${ENDPOINT}/api/worktrees" + fi + ;; + search) QUERY="${1:-}" WS="$(norm_ws "${2:-}")" @@ -126,6 +148,39 @@ with urllib.request.urlopen(req) as resp: " "${SYM}" "${WS}" ;; + relate) + SRC="${1:-}" + TGT="${2:-}" + TYPE="${3:-CALLS}" + WS="$(norm_ws "${4:-}")" + if [ -z "${SRC}" ] || [ -z "${TGT}" ]; then + echo "❌ Usage: omni.sh relate [relation_type] [workspace]" + exit 1 + fi + python3 -c " +import urllib.request, json, sys +url = '${ENDPOINT}/api/relationships' +payload_data = { + 'source_symbol': sys.argv[1], + 'target_symbol': sys.argv[2], + 'type': sys.argv[3], + 'category': 'INFERRED', + 'workspace': sys.argv[4] if sys.argv[4] else 'default' +} +payload = json.dumps(payload_data).encode('utf-8') +req = urllib.request.Request(url, data=payload, headers={'Content-Type': 'application/json'}) +try: + with urllib.request.urlopen(req) as resp: + data = json.loads(resp.read().decode()) + print(f\"βœ… Successfully linked: {data.get('source')} -[{data.get('type')}]-> {data.get('target')}\") + print(f\" Relationship ID: {data.get('relationship_id')}\") + print(f\" Category: {data.get('category')}\") +except Exception as e: + print(f'❌ Error augmenting relationship: {e}') + sys.exit(1) +" "${SRC}" "${TGT}" "${TYPE}" "${WS}" + ;; + condense) SYMBOL="${1:-}" WS="$(norm_ws "${2:-}")" @@ -237,9 +292,37 @@ except Exception as e: RAW_PATH="${1:-/workspace}" PROJECT="${2:-}" - # Resolve host paths to absolute paths - if [ "${RAW_PATH}" != "/workspace" ] && [ -d "${RAW_PATH}" ]; then + # Guardrails: Check path validity before making Docker API call + if [ "${RAW_PATH}" != "/workspace" ]; then + if [ -f "${RAW_PATH}" ]; then + echo "❌ ERROR: Target path is a file, not a directory: ${RAW_PATH}" + echo "πŸ’‘ Omni-Graph indexes entire directory trees. Did you mean: $(dirname "${RAW_PATH}")" + exit 1 + fi + + if [ ! -e "${RAW_PATH}" ]; then + echo "❌ ERROR: Target directory does not exist on host:" + echo " '${RAW_PATH}'" + PARENT_DIR="$(dirname "${RAW_PATH}")" + BASE_NAME="$(basename "${RAW_PATH}")" + if [ -d "${PARENT_DIR}" ]; then + echo "" + echo "πŸ’‘ Existing folders in '${PARENT_DIR}':" + find "${PARENT_DIR}" -maxdepth 1 -mindepth 1 -type d | grep -i "${BASE_NAME:0:3}" | head -n 5 | while IFS= read -r match; do + echo " β€’ ${match}" + done || true + fi + exit 1 + fi + RESOLVED_PATH="$(cd "${RAW_PATH}" && pwd)" + + case "${RESOLVED_PATH}" in + / | /root | /bin | /sbin | /usr | /System* | /Library* | /Applications* | /etc* | /var* | /private*) + echo "πŸ›‘ ERROR: Refusing to ingest protected system directory: ${RESOLVED_PATH}" + exit 1 + ;; + esac else RESOLVED_PATH="${RAW_PATH}" fi @@ -268,6 +351,8 @@ try: print(f\" β€’ Files Skipped: {result.get('files_skipped')} (unchanged cache)\") print(f\" β€’ Nodes Created: {result.get('nodes_created')}\") print(f\" β€’ Edges Created: {result.get('edges_created')}\") + if result.get('clusters_computed') is not None: + print(f\" β€’ Clusters: {result.get('clusters_computed')} modular galaxy subsystems\") print(f\" β€’ Duration: {result.get('duration_ms')}ms\") except urllib.error.HTTPError as e: body = e.read().decode() @@ -283,6 +368,120 @@ except Exception as e: " "${RESOLVED_PATH}" "${PROJECT}" ;; + watch) + SUB="${1:-}" + shift || true + case "${SUB}" in + start) + DIR="${1:-}" + PROJ="${2:-}" + DEBOUNCE="${3:-500}" + if [ -z "${DIR}" ]; then echo "❌ Missing directory path. Usage: omni.sh watch start [project] [debounce_ms]"; exit 1; fi + if [ -d "${DIR}" ]; then + RESOLVED="$(cd "${DIR}" && pwd)" + else + RESOLVED="${DIR}" + fi + python3 -c " +import urllib.request, json, sys +data = json.dumps({'path': sys.argv[1], 'project': sys.argv[2] or None, 'debounce_ms': int(sys.argv[3])}).encode() +req = urllib.request.Request('${ENDPOINT}/api/watch/start', data=data, headers={'Content-Type': 'application/json'}) +try: + with urllib.request.urlopen(req) as resp: + res = json.loads(resp.read().decode()) + print('🟒 Live Watch Started!') + print(f\" β€’ Workspace: {res.get('workspace')}\") + print(f\" β€’ Path: {res.get('path')}\") + print(f\" β€’ Files Tracked: {res.get('files_tracked')}\") + print(f\" β€’ Debounce: {res.get('debounce_ms')}ms\") +except urllib.error.HTTPError as e: + print(f'❌ Failed to start watch ({e.code}): {e.read().decode()}') +except Exception as e: + print(f'❌ Error: {e}') +" "${RESOLVED}" "${PROJ}" "${DEBOUNCE}" + ;; + stop) + WS="$(norm_ws "${1:-}")" + if [ -z "${WS}" ]; then echo "❌ Missing workspace name. Usage: omni.sh watch stop "; exit 1; fi + python3 -c " +import urllib.request, json, sys +data = json.dumps({'workspace': sys.argv[1]}).encode() +req = urllib.request.Request('${ENDPOINT}/api/watch/stop', data=data, headers={'Content-Type': 'application/json'}) +try: + with urllib.request.urlopen(req) as resp: + res = json.loads(resp.read().decode()) + print(f\"πŸ›‘ Live Watch Stopped for workspace '{res.get('workspace')}':\") + print(f\" β€’ Events Processed: {res.get('events_processed')}\") + print(f\" β€’ Files Re-indexed: {res.get('files_reindexed')}\") + print(f\" β€’ Files Deleted: {res.get('files_deleted')}\") +except urllib.error.HTTPError as e: + print(f'❌ Failed to stop watch ({e.code}): {e.read().decode()}') +except Exception as e: + print(f'❌ Error: {e}') +" "${WS}" + ;; + status) + python3 -c " +import urllib.request, json +req = urllib.request.Request('${ENDPOINT}/api/watch/status') +try: + with urllib.request.urlopen(req) as resp: + watchers = json.loads(resp.read().decode()) + if not watchers: + print('No active live watchers. Run: ./scripts/omni.sh watch start [project]') + exit(0) + print(f'{\"WORKSPACE\":<20} {\"STATUS\":<12} {\"FILES\":<8} {\"EVENTS\":<8} {\"REINDEX\":<8} {\"AVG(ms)\":<8} {\"PATH\"}') + print('='*80) + for w in watchers: + print(f\"{w.get('workspace'):<20} {w.get('status'):<12} {w.get('files_tracked',0):<8} {w.get('events_processed',0):<8} {w.get('files_reindexed',0):<8} {w.get('avg_sync_ms',0):<8} {w.get('path')}\") +except Exception as e: + print(f'❌ Error: {e}') +" + ;; + fidelity) + WS="$(norm_ws "${1:-}")" + python3 -c " +import urllib.request, urllib.parse, json, sys +url = '${ENDPOINT}/api/watch/fidelity' +if sys.argv[1]: + url += '?' + urllib.parse.urlencode({'workspace': sys.argv[1]}) +req = urllib.request.Request(url) +try: + with urllib.request.urlopen(req) as resp: + data = json.loads(resp.read().decode()) + ws = data.get('workspace') or 'All Workspaces' + score = data.get('fidelity_score', 1.0) + state = data.get('convergence_state', 'converged') + gen = data.get('graph_generation', 0) + nodes = data.get('node_count', 0) + edges = data.get('edge_count', 0) + dangling = data.get('dangling_directory_edges', 0) + unresolved = data.get('unresolved_edges', 0) + rev_inval = data.get('reverse_invalidation_count', 0) + print(f'πŸ”¬ Nanometer Fidelity Diagnostics for [{ws}]:\n') + print(f' β€’ Fidelity Score: {score:.4f} ({\"100% Relational Parity\" if score == 1.0 else \"Degraded\"})') + print(f' β€’ Convergence State: {state.upper()}') + print(f' β€’ Graph Generation: #{gen}') + print(f' β€’ Total Graph Nodes: {nodes:,}') + print(f' β€’ Total Graph Edges: {edges:,}') + print(f' β€’ Dangling Directory Edges: {dangling}') + print(f' β€’ Unresolved Forward Edges: {unresolved}') + print(f' β€’ Reverse Invalidations: {rev_inval}') +except Exception as e: + print(f'❌ Error querying fidelity: {e}') +" "${WS}" + ;; + events) + echo "πŸ“‘ Streaming live delta events from ${ENDPOINT}/api/watch/events (Ctrl+C to stop)..." + curl -N -s "${ENDPOINT}/api/watch/events" + ;; + *) + echo "Usage: omni.sh watch " + exit 1 + ;; + esac + ;; + stats) curl -sf "${ENDPOINT}/api/stats" | python3 -m json.tool 2>/dev/null || curl -s "${ENDPOINT}/api/stats" ;; diff --git a/AGENTS.md b/AGENTS.md index 7cd423a..c6be165 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,3 +11,11 @@ 2. **Context Condensation**: Retrieve 2-hop topological call chains (<1500 tokens) instead of reading multiple raw files. 3. **Semantic Search**: Use `http://localhost:8080/api/search?q=...` for vector similarity lookup across functions, classes, and types. 4. **Enforced Rules**: Read [`.agents/rules/08-omni-graph-enforcement.md`](.agents/rules/08-omni-graph-enforcement.md). + +--- + +## 🧭 Omni-Graph Semantic Knowledge Hub Integration +This workspace is monitored and enforced by Omni-Graph. +- Query AST definitions: `http://localhost:8080/api/symbol?name=` +- Trace references & callers: `http://localhost:8080/api/references?symbol=` +- Enforced Rule: Read [`.agents/rules/00-omni-graph-mandatory-retrieval.md`](.agents/rules/00-omni-graph-mandatory-retrieval.md)