agent-operating-substrate 0.1.0__py3-none-any.whl

aos/ingest.py

@@ -0,0 +1,251 @@
+"""Automated repository ingestion and convention extraction engine."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import re
+import time
+from typing import Any
+import yaml
+
+from aos.autopsy import inscribe_candidate, promote_candidate, synthesize_candidate_rule
+from aos.blackboard import post_event
+
+
+@dataclass
+class IngestionReport:
+    detected_languages: list[str] = field(default_factory=list)
+    detected_frameworks: list[str] = field(default_factory=list)
+    scanned_config_files: list[str] = field(default_factory=list)
+    existing_instruction_files: list[str] = field(default_factory=list)
+    synthesized_rules: list[dict[str, Any]] = field(default_factory=list)
+    recommended_packs: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "detected_languages": self.detected_languages,
+            "detected_frameworks": self.detected_frameworks,
+            "scanned_config_files": self.scanned_config_files,
+            "existing_instruction_files": self.existing_instruction_files,
+            "recommended_packs": self.recommended_packs,
+            "synthesized_rules_count": len(self.synthesized_rules),
+            "synthesized_rules": self.synthesized_rules,
+        }
+
+
+def scan_repository_conventions(root_dir: Path | str = ".") -> IngestionReport:
+    """Inspect repository manifests and instruction files to derive tailored invariants."""
+    root = Path(root_dir)
+    report = IngestionReport()
+    detected_rules: list[dict[str, Any]] = []
+
+    # 1. Check TypeScript / JavaScript ecosystems
+    tsconfig = root / "tsconfig.json"
+    if tsconfig.is_file():
+        report.detected_languages.append("typescript")
+        report.scanned_config_files.append("tsconfig.json")
+        try:
+            ts_text = tsconfig.read_text(encoding="utf-8", errors="ignore")
+            clean_ts = re.sub(r"//.*", "", ts_text)
+            ts_data = json.loads(clean_ts)
+            co = ts_data.get("compilerOptions", {})
+            if co.get("strict", False) or co.get("noImplicitAny", False):
+                detected_rules.append({
+                    "id": "ts-strict-typing",
+                    "statement": "TypeScript code must maintain strict type safety: avoid explicit any casts or unvalidated dynamic properties.",
+                    "rationale": "Enforce strict compiler options declared in tsconfig.json across all AI edits.",
+                    "paths": ["src/**/*.ts", "src/**/*.tsx"],
+                    "languages": ["typescript"],
+                    "enforcement": "reject_diff",
+                })
+        except Exception:
+            pass
+
+    pkg_json = root / "package.json"
+    if pkg_json.is_file():
+        report.scanned_config_files.append("package.json")
+        try:
+            pkg_data = json.loads(pkg_json.read_text(encoding="utf-8", errors="ignore"))
+            deps = {**pkg_data.get("dependencies", {}), **pkg_data.get("devDependencies", {})}
+            if "react" in deps:
+                report.detected_frameworks.append("react")
+                if "javascript" not in report.detected_languages:
+                    report.detected_languages.append("javascript")
+                detected_rules.append({
+                    "id": "react-hooks-deps",
+                    "statement": "React components must obey the rules of hooks and specify complete dependency arrays in useEffect and useMemo.",
+                    "rationale": "Prevents stale closure bugs and infinite re-render cycles in React components.",
+                    "paths": ["src/**/*.jsx", "src/**/*.tsx"],
+                    "languages": ["javascript", "typescript"],
+                    "enforcement": "reject_diff",
+                })
+            if "next" in deps:
+                report.detected_frameworks.append("nextjs")
+                detected_rules.append({
+                    "id": "nextjs-client-boundary",
+                    "statement": "Interactive components utilizing state or browser hooks must explicitly declare the 'use client' directive.",
+                    "rationale": "Next.js App Router enforces strict server and client component boundaries.",
+                    "paths": ["src/app/**/*.tsx", "src/components/**/*.tsx"],
+                    "languages": ["typescript", "javascript"],
+                    "enforcement": "reject_diff",
+                })
+        except Exception:
+            pass
+
+    # 2. Check Python ecosystems
+    pyproject = root / "pyproject.toml"
+    reqs = root / "requirements.txt"
+    is_python = False
+    py_text = ""
+
+    if pyproject.is_file():
+        is_python = True
+        report.scanned_config_files.append("pyproject.toml")
+        py_text += pyproject.read_text(encoding="utf-8", errors="ignore")
+
+    if reqs.is_file():
+        is_python = True
+        report.scanned_config_files.append("requirements.txt")
+        py_text += reqs.read_text(encoding="utf-8", errors="ignore")
+
+    if is_python:
+        report.detected_languages.append("python")
+        if "fastapi" in py_text.lower():
+            report.detected_frameworks.append("fastapi")
+            detected_rules.append({
+                "id": "fastapi-pydantic-schemas",
+                "statement": "FastAPI route handlers must define explicit Pydantic request and response models for typed I/O contracts.",
+                "rationale": "Ensures runtime schema validation and automatic OpenAPI documentation generation.",
+                "paths": ["src/**/*.py", "app/**/*.py"],
+                "languages": ["python"],
+                "enforcement": "reject_diff",
+            })
+        if "django" in py_text.lower():
+            report.detected_frameworks.append("django")
+            detected_rules.append({
+                "id": "django-atomic-writes",
+                "statement": "Mutating database operations across multiple models must execute within transaction.atomic() blocks.",
+                "rationale": "Guarantees database consistency and prevents partial write corruptions.",
+                "paths": ["src/**/*.py"],
+                "languages": ["python"],
+                "enforcement": "reject_diff",
+            })
+
+    # 3. Check Rust
+    cargo = root / "Cargo.toml"
+    if cargo.is_file():
+        report.detected_languages.append("rust")
+        report.scanned_config_files.append("Cargo.toml")
+        detected_rules.append({
+            "id": "rust-unsafe-audit",
+            "statement": "Unsafe blocks in Rust must include a preceding '// SAFETY:' comment explaining pointer or memory validity invariants.",
+            "rationale": "Audit requirement ensuring memory safety invariants are documented at each unsafe boundary.",
+            "paths": ["src/**/*.rs"],
+            "languages": ["rust"],
+            "enforcement": "reject_diff",
+        })
+
+    # 4. Check Go
+    gomod = root / "go.mod"
+    if gomod.is_file():
+        report.detected_languages.append("go")
+        report.scanned_config_files.append("go.mod")
+        detected_rules.append({
+            "id": "go-error-wrapping",
+            "statement": "Go functions must explicitly check and wrap returned errors using fmt.Errorf with %w.",
+            "rationale": "Preserves error call chains and enables errors.Is / errors.As inspection in Go services.",
+            "paths": ["**/*.go"],
+            "languages": ["go"],
+            "enforcement": "reject_diff",
+        })
+
+    # 5. Scan Existing Team Instruction Files
+    instruction_candidates = [
+        "CLAUDE.md",
+        "AGENTS.md",
+        ".cursorrules",
+        "CONTRIBUTING.md",
+        ".github/copilot-instructions.md",
+    ]
+    for instr_name in instruction_candidates:
+        instr_path = root / instr_name
+        if instr_path.is_file():
+            report.existing_instruction_files.append(instr_name)
+            try:
+                instr_text = instr_path.read_text(encoding="utf-8", errors="ignore")
+                clean_instr = re.sub(r"<!-- AOS_INVARIANTS_START -->.*?<!-- AOS_INVARIANTS_END -->", "", instr_text, flags=re.DOTALL)
+                rule_lines = re.findall(r"^(?:[-*]|\d+\.)\s+([A-Z][^\n]{15,120})", clean_instr, re.MULTILINE)
+                for idx, r_stmt in enumerate(rule_lines[:3], 1):
+                    safe_id = re.sub(r"[^a-z0-9]+", "-", instr_name.lower().replace(".", "-")).strip("-")
+                    r_id = f"team-{safe_id}-rule-{idx}"
+                    clean_stmt = r_stmt.strip()
+                    if not clean_stmt.endswith("."):
+                        clean_stmt += "."
+                    if not any(d["statement"] == clean_stmt for d in detected_rules):
+                        detected_rules.append({
+                            "id": r_id,
+                            "statement": clean_stmt,
+                            "rationale": f"Extracted from team repository instructions in {instr_name}.",
+                            "paths": ["**/*"],
+                            "languages": [],
+                            "enforcement": "reject_diff",
+                        })
+            except Exception:
+                pass
+
+    from aos.packs import recommend_packs
+    report.recommended_packs = recommend_packs(root_dir=root)
+    report.synthesized_rules = detected_rules
+    return report
+
+
+def ingest_repository(
+    root_dir: Path | str = ".",
+    auto_promote: bool = False,
+    install_recommended_packs: bool = False,
+) -> IngestionReport:
+    """Scan repository conventions and inscribe synthesized invariants into the substrate."""
+    root = Path(root_dir)
+    report = scan_repository_conventions(root_dir=root)
+    sub_dir = root / ".agents" / "substrate"
+
+    for rule_data in report.synthesized_rules:
+        candidate = synthesize_candidate_rule(
+            rule_id=rule_data["id"],
+            statement=rule_data["statement"],
+            rationale=rule_data.get("rationale", "Synthesized via repository ingestion scan."),
+            paths=rule_data.get("paths", ["**/*"]),
+            languages=rule_data.get("languages", []),
+            enforcement=rule_data.get("enforcement", "reject_diff"),
+            incident_id=f"ingest-{int(time.time())}",
+            inscribing_agent="repo-ingestion-engine",
+        )
+
+        inscribe_candidate(candidate, substrate_dir=sub_dir)
+        if auto_promote:
+            promote_candidate(candidate.id, peer_agent="repo-ingestion-engine", substrate_dir=sub_dir)
+
+    if install_recommended_packs:
+        from aos.packs import install_pack
+        for p in report.recommended_packs:
+            install_pack(p, root_dir=root, promote=auto_promote)
+
+    post_event(
+        {
+            "type": "REPO_INGESTED",
+            "sender": "repo-ingestion-engine",
+            "payload": {
+                "detected_languages": report.detected_languages,
+                "detected_frameworks": report.detected_frameworks,
+                "scanned_config_files": report.scanned_config_files,
+                "existing_instruction_files": report.existing_instruction_files,
+                "synthesized_count": len(report.synthesized_rules),
+                "auto_promoted": auto_promote,
+            },
+        },
+        root_dir=root,
+    )
+
+    return report

aos/matcher.py

@@ -0,0 +1,125 @@
+"""Matching engine for invariant rule scopes (paths and languages)."""
+
+from __future__ import annotations
+import glob
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+from aos.models import InvariantRule
+
+EXTENSION_LANGUAGE_MAP: dict[str, str] = {
+    ".py": "python",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".cxx": "cpp",
+    ".hpp": "cpp",
+    ".hxx": "cpp",
+    ".h": "cpp",
+    ".c": "c",
+    ".cu": "cuda",
+    ".cuh": "cuda",
+    ".rs": "rust",
+    ".go": "go",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".ts": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".java": "java",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".json": "json",
+    ".sh": "bash",
+    ".bash": "bash",
+}
+
+
+@lru_cache(maxsize=4096)
+def _compile_glob(pattern: str) -> re.Pattern[str]:
+    # Normalize slashes in pattern
+    normalized_pattern = pattern.replace("\\", "/")
+    regex_str = glob.translate(normalized_pattern, recursive=True, include_hidden=True)
+    return re.compile(regex_str)
+
+
+@lru_cache(maxsize=4096)
+def normalize_path(path: str) -> str:
+    """Normalize file path to POSIX style without leading relative prefixes."""
+    p = path.replace("\\", "/")
+    if p.startswith("./"):
+        p = p[2:]
+    return p
+
+
+def match_path(pattern: str, target_path: str) -> bool:
+    """Match a target path against a glob pattern with globstar (**) support."""
+    normalized = normalize_path(target_path)
+    regex = _compile_glob(pattern)
+    return bool(regex.match(normalized))
+
+
+@lru_cache(maxsize=4096)
+def infer_language(file_path: str) -> Optional[str]:
+    """Infer the programming language identifier from a file path extension."""
+    dot_idx = file_path.rfind(".")
+    if dot_idx == -1:
+        return None
+    slash_idx = max(file_path.rfind("/"), file_path.rfind("\\"))
+    if dot_idx <= slash_idx:
+        return None
+    suffix = file_path[dot_idx:].lower()
+    return EXTENSION_LANGUAGE_MAP.get(suffix)
+
+
+@lru_cache(maxsize=4096)
+def extract_path_prefix(pattern: str) -> str:
+    """Extract literal directory prefix before any glob wildcard character."""
+    norm = normalize_path(pattern)
+    wildcard_indices = [norm.find(ch) for ch in ("*", "?", "[") if norm.find(ch) != -1]
+    limit = min(wildcard_indices) if wildcard_indices else len(norm)
+    literal_prefix = norm[:limit]
+    slash_idx = literal_prefix.rfind("/")
+    if slash_idx != -1:
+        return literal_prefix[: slash_idx + 1]
+    return ""
+
+
+def get_rule_prefixes(rule: InvariantRule) -> list[str]:
+    """Extract path prefixes associated with a rule."""
+    if not rule.scope.paths:
+        return [""]
+    prefixes: list[str] = []
+    for pat in rule.scope.paths:
+        pfx = extract_path_prefix(pat)
+        if pfx == "":
+            return [""]
+        prefixes.append(pfx)
+    return prefixes
+
+
+def match_rule(
+    rule: InvariantRule,
+    target_path: str,
+    target_language: Optional[str] = None,
+) -> bool:
+    """Check if an invariant rule applies to the specified file and language."""
+    norm_path = normalize_path(target_path)
+
+    # Path scope check
+    if rule.scope.paths:
+        path_matched = any(match_path(pat, norm_path) for pat in rule.scope.paths)
+        if not path_matched:
+            return False
+
+    # Language scope check
+    if rule.scope.languages:
+        resolved_lang = target_language.lower() if target_language else infer_language(norm_path)
+        if not resolved_lang:
+            return False
+        if not any(lang.lower() == resolved_lang for lang in rule.scope.languages):
+            return False
+
+    return True

aos/mcp.py

@@ -0,0 +1,188 @@
+"""Model Context Protocol (MCP) server for universal agent harness integration."""
+
+from __future__ import annotations
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from aos.autopsy import inscribe_candidate, synthesize_candidate_rule
+from aos.blackboard import post_event, read_events
+from aos.engine import RuleEngine
+from aos.enforcer import enforce_all
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+def get_tool_definitions() -> list[dict[str, Any]]:
+    return [
+        {
+            "name": "aos_rules_check",
+            "description": "Evaluate target file paths against active substrate invariant rules.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "files": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of file paths to check.",
+                    },
+                },
+                "required": ["files"],
+            },
+        },
+        {
+            "name": "aos_rules_list",
+            "description": "List all discovered invariant rules in the substrate.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "status": {
+                        "type": "string",
+                        "enum": ["active", "candidate", "archive"],
+                        "description": "Filter by rule status.",
+                    },
+                },
+            },
+        },
+        {
+            "name": "aos_autopsy",
+            "description": "Inscribe a new candidate invariant rule derived from a failure autopsy.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Unique rule identifier."},
+                    "statement": {"type": "string", "description": "Invariant directive statement."},
+                    "rationale": {"type": "string", "description": "Technical justification."},
+                    "paths": {"type": "array", "items": {"type": "string"}, "description": "Path globs."},
+                    "languages": {"type": "array", "items": {"type": "string"}, "description": "Languages."},
+                    "incident_id": {"type": "string", "description": "Incident reference."},
+                },
+                "required": ["id", "statement", "rationale", "paths"],
+            },
+        },
+        {
+            "name": "aos_blackboard_post",
+            "description": "Broadcast an event or intent announcement on the local peer blackboard.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "type": {"type": "string", "description": "Event type."},
+                    "sender": {"type": "string", "description": "Agent identifier."},
+                    "payload": {"type": "object", "description": "Arbitrary payload mapping."},
+                },
+                "required": ["type", "sender", "payload"],
+            },
+        },
+    ]
+
+
+def handle_tool_call(name: str, args: dict[str, Any], root_dir: Path) -> str:
+    if name == "aos_rules_check":
+        files = args.get("files", [])
+        engine = RuleEngine(root_dir=root_dir)
+        matches = engine.match_files(files, status="active")
+        violations = enforce_all(files, root_dir=root_dir)
+
+        output: dict[str, Any] = {"matches": {}, "violations": []}
+        for f, rules in matches.items():
+            output["matches"][f] = [r.to_dict() for r in rules]
+        output["violations"] = [
+            {
+                "file_path": v.file_path,
+                "rule_id": v.rule_id,
+                "message": v.message,
+                "enforcement": v.enforcement,
+                "line": v.line_number,
+            }
+            for v in violations
+        ]
+        return json.dumps(output, indent=2)
+
+    elif name == "aos_rules_list":
+        status = args.get("status")
+        engine = RuleEngine(root_dir=root_dir)
+        rules = engine.get_rules(status=status)
+        return json.dumps([r.to_dict() for r in rules], indent=2)
+
+    elif name == "aos_autopsy":
+        rule = synthesize_candidate_rule(
+            rule_id=args["id"],
+            statement=args["statement"],
+            rationale=args["rationale"],
+            paths=args["paths"],
+            languages=args.get("languages", []),
+            incident_id=args.get("incident_id", "inc-mcp"),
+            inscribing_agent="mcp-client-agent",
+        )
+        saved = inscribe_candidate(rule, substrate_dir=root_dir / ".agents" / "substrate")
+        return json.dumps({"status": "inscribed", "path": str(saved)})
+
+    elif name == "aos_blackboard_post":
+        ev = post_event(
+            {
+                "type": args["type"],
+                "sender": args["sender"],
+                "payload": args["payload"],
+            },
+            root_dir=root_dir,
+        )
+        return json.dumps({"status": "posted", "event_id": ev.event_id})
+
+    return json.dumps({"error": f"Unknown tool: {name}"})
+
+
+def run_mcp_server(root_dir: Path | str = ".") -> None:
+    """Run the JSON-RPC stdio loop."""
+    root = Path(root_dir)
+    for line in sys.stdin:
+        line_str = line.strip()
+        if not line_str:
+            continue
+        try:
+            req = json.loads(line_str)
+        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": PROTOCOL_VERSION,
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": "aos-mcp-server", "version": "0.1.0"},
+                },
+            }
+        elif method == "tools/list":
+            res = {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {"tools": get_tool_definitions()},
+            }
+        elif method == "tools/call":
+            tool_name = params.get("name", "")
+            tool_args = params.get("arguments", {})
+            text_result = handle_tool_call(tool_name, tool_args, root)
+            res = {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {
+                    "content": [{"type": "text", "text": text_result}],
+                },
+            }
+        elif method == "notifications/initialized":
+            continue
+        else:
+            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()