code-context-control 2.28.0__py3-none-any.whl

core/__init__.py

@@ -0,0 +1,75 @@
+"""Token counting and measurement utilities."""
+import hashlib
+import re
+from functools import lru_cache
+
+# Lazy-loaded tiktoken encoder
+_encoder = None
+
+# LRU cache keyed on content hash — avoids redundant tiktoken encodes
+# within a session where the same code chunks are counted repeatedly.
+_TOKEN_CACHE_MAX = 2048
+
+@lru_cache(maxsize=_TOKEN_CACHE_MAX)
+def _cached_count(content_hash: str, length: int, text: str) -> int:
+    """Count tokens with LRU memoization. length param ensures hash collisions are safe."""
+    encoder = _get_encoder()
+    if encoder:
+        return len(encoder.encode(text))
+    tokens = re.findall(r'\w+|[^\w\s]', text)
+    count = 0
+    for t in tokens:
+        if len(t) <= 4:
+            count += 1
+        else:
+            count += max(1, len(t) // 4)
+    return count
+
+def _get_encoder():
+    """Lazy-load tiktoken encoder (one-time cost)."""
+    global _encoder
+    if _encoder is None:
+        try:
+            import tiktoken
+            _encoder = tiktoken.get_encoding("cl100k_base")
+        except (ImportError, Exception):
+            _encoder = False  # Sentinel: tiktoken unavailable
+    return _encoder
+
+def count_tokens(text: str) -> int:
+    """
+    Count tokens using tiktoken (cl100k_base) with LRU caching.
+    Repeated calls with identical text hit the cache (~0ms vs ~1-2ms).
+    Falls back to heuristic if tiktoken is unavailable.
+    """
+    if not text:
+        return 0
+    # For short strings (<50 chars), hashing overhead > tiktoken cost — skip cache
+    if len(text) < 50:
+        encoder = _get_encoder()
+        if encoder:
+            return len(encoder.encode(text))
+        return len(re.findall(r'\w+|[^\w\s]', text))
+    h = hashlib.md5(text.encode("utf-8", errors="replace")).hexdigest()
+    return _cached_count(h, len(text), text)
+
+def measure_savings(original: str, compressed: str) -> dict:
+    """Measure token savings between original and compressed text."""
+    orig_tokens = count_tokens(original)
+    comp_tokens = count_tokens(compressed)
+    saved = orig_tokens - comp_tokens
+    pct = (saved / orig_tokens * 100) if orig_tokens > 0 else 0
+    return {
+        "original_tokens": orig_tokens,
+        "compressed_tokens": comp_tokens,
+        "saved_tokens": saved,
+        "savings_pct": round(pct, 1)
+    }
+
+def format_token_count(n: int) -> str:
+    """Human-readable token count."""
+    if n >= 1_000_000:
+        return f"{n/1_000_000:.1f}M"
+    elif n >= 1_000:
+        return f"{n/1_000:.1f}K"
+    return str(n)

core/config.py

@@ -0,0 +1,269 @@
+"""Hybrid configuration loader for C3 v2.3 features.
+
+Loads the "hybrid" section from .c3/config.json with sensible defaults.
+All three tiers (output filter, router, SLTM) can be independently disabled.
+"""
+import json
+from pathlib import Path
+
+DEFAULTS = {
+    "ollama_base_url": "http://localhost:11434",
+    "HYBRID_DISABLE_TIER1": False,   # Output filter
+    "HYBRID_DISABLE_TIER2": False,   # Router
+    "HYBRID_DISABLE_SLTM": False,    # Vector memory
+    "show_context_nudges": True,     # Append budget nudge when over threshold
+    "prepend_notifications": True,   # Prepend agent notifications to tool/chat responses
+    # Model assignments
+    "embed_model": "nomic-embed-text",
+    "filter_model": "gemma3n:latest",
+    "summary_model": "gemma3n:latest",
+    "simple_qa_model": "deepseek-r1:1.5b",
+    "complex_model": "llama3.2:3b",
+    # Router params
+    "router_log_threshold": 500,     # tokens: route to log_summary
+    "router_simple_threshold": 100,  # tokens: route to simple_qa
+    "router_allow_model_fallback": True,
+    "router_fallback_models": [],    # Optional ordered model fallbacks
+    "router_retry_on_empty": True,   # Retry with fallback when first model returns no response
+    "validate_timeout_seconds": 12,  # Hard timeout for c3_validate native syntax checks
+    # Filter params
+    "filter_llm_threshold": 500,     # tokens: trigger LLM pass
+    # SLTM params
+    "sltm_alpha": 0.5,               # TF-IDF weight in hybrid search (1-alpha = vector weight)
+    "sltm_min_score": 0.3,           # Minimum similarity threshold for VectorStore search
+    # Auto-memory: background learning from tool calls
+    "auto_memory": {
+        "enabled": True,             # Set False to disable all auto-extraction
+    },
+    # Local RAG Pipeline: auto-retrieve project docs on session start
+    "rag": {
+        "enabled": True,
+        "max_precontext_tokens": 400,
+    },
+    # Edit Ledger: auto-log Edit/Write operations
+    "edit_ledger": {
+        "enabled": True,
+        "tracking_level": "standard",  # "minimal", "standard", "detailed"
+        "auto_tag": True,              # Auto-tag edits from hooks
+    },
+    # c3_agent compound workflows
+    "agent_workflows": {
+        "enabled": True,
+        "prefetch_max_files": 3,          # Max files to auto-compress on search prefetch
+        "batch_validate_max_files": 10,   # Max files in a single batch validate call
+        "compound_max_compress": 5,       # Max files to compress in compound workflows
+        "delegate_in_workflows": True,    # Allow Ollama delegation in compound workflows
+    },
+}
+
+
+def load_hybrid_config(project_path: str) -> dict:
+    """Load hybrid config from .c3/config.json, merged with defaults."""
+    config_file = Path(project_path) / ".c3" / "config.json"
+    hybrid = {}
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data = json.load(f)
+            hybrid = data.get("hybrid", {})
+        except Exception:
+            pass
+    merged = {**DEFAULTS, **hybrid}
+    if "show_savings_footer" not in hybrid and "SHOW_SAVINGS_SUMMARY" in hybrid:
+        merged["show_savings_footer"] = bool(hybrid.get("SHOW_SAVINGS_SUMMARY"))
+    if "validate_timeout_seconds" not in hybrid and "validate_review_timeout_seconds" in hybrid:
+        merged["validate_timeout_seconds"] = int(hybrid.get("validate_review_timeout_seconds") or DEFAULTS["validate_timeout_seconds"])
+    merged["SHOW_SAVINGS_SUMMARY"] = bool(merged.get("show_savings_footer", False))
+    return merged
+
+
+# ─── Agent Defaults ────────────────────────────────────────
+
+FILE_MEMORY_DEFAULTS = {
+    "enabled": True,
+    "max_tracked_files": 200,
+    "summary_model": "gemma3n:latest",
+    "summary_max_tokens": 80,
+    "nudge_threshold": 500,        # Min chars in Read result to trigger nudge
+    "auto_index_on_read": True,    # Auto-index files when Read hook fires
+}
+
+
+# Keep in sync with services/agents.py:create_agents factory defaults.
+# Core (always-on by default): IndexStaleness, FileMemory, EditLedgerEnricher.
+# Everything else defaults off; users opt in via the UI / config.
+AGENT_DEFAULTS = {
+    "IndexStaleness": {
+        "enabled": True, "interval": 60, "use_ai": False,
+        "ai_model": "gemma3n:latest", "warn_threshold": 5, "rebuild_threshold": 15,
+    },
+    "MemoryPruner": {
+        "enabled": False, "interval": 300, "use_ai": True,
+        "ai_model": "gemma3n:latest", "embed_model": "nomic-embed-text",
+        "similarity_threshold": 0.8,
+    },
+    "ClaudeMdDrift": {
+        "enabled": False, "interval": 120, "use_ai": False, "ai_model": "gemma3n:latest",
+    },
+    "SessionInsight": {
+        "enabled": False, "interval": 600, "use_ai": True,
+        "ai_model": "gemma3n:latest", "min_tool_calls": 10,
+    },
+    "AutonomyPlanner": {
+        "enabled": False, "interval": 240, "use_ai": True,
+        "ai_model": "gemma3n:latest", "lookback_tool_calls": 30,
+        "cooldown_seconds": 600, "min_signal_score": 2, "max_actions": 3,
+    },
+    "ClaudeMdUpdater": {
+        "enabled": False, "interval": 900, "use_ai": True,
+        "ai_model": "gemma3n:latest", "auto_apply": True,
+        "min_facts_for_promote": 2,
+    },
+    "FileMemory": {
+        "enabled": True, "interval": 120, "use_ai": False,
+        "ai_model": "gemma3n:latest", "max_files_per_cycle": 5,
+    },
+    "DelegateCoach": {
+        "enabled": False, "interval": 300, "use_ai": False,
+        "ai_model": "gemma3n:latest", "lookback_lines": 100,
+    },
+    "KeyFileVersion": {
+        "enabled": False, "interval": 180, "use_ai": False,
+        "ai_model": "gemma3n:latest", "agent_target": "current",
+        "max_changes_per_notice": 4,
+    },
+    "EditLedgerEnricher": {
+        "enabled": True, "interval": 10, "use_ai": False,
+    },
+}
+
+
+# ─── Proxy Defaults ────────────────────────────────────────
+
+PROXY_DEFAULTS = {
+    "always_visible": ["core"],      # Categories always visible when proxy filtering is enabled
+    "max_tools": 12,
+    "filter_tools": True,            # True = dynamic filtering by category, False = show all
+    "use_slm": True,
+    "slm_model": "gemma3n:latest",
+    "context_window_size": 10,
+    "inject_context_summary": False,
+    "PROXY_DISABLE": False,
+}
+
+
+def load_proxy_config(project_path: str) -> dict:
+    """Load proxy config from .c3/config.json, merged with defaults."""
+    config_file = Path(project_path) / ".c3" / "config.json"
+    proxy = {}
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data = json.load(f)
+            proxy = data.get("proxy", {})
+        except Exception:
+            pass
+    merged = {**PROXY_DEFAULTS, **proxy}
+    always_visible = merged.get("always_visible", ["core"])
+    if isinstance(always_visible, str):
+        always_visible = [always_visible]
+    merged["always_visible"] = always_visible or ["core"]
+    return merged
+
+
+def load_mcp_config(project_path: str) -> dict:
+    """Load MCP mode config from .c3/config.json, merged with defaults."""
+    config_file = Path(project_path) / ".c3" / "config.json"
+    mcp = {}
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data = json.load(f)
+            mcp = data.get("mcp", {})
+        except Exception:
+            pass
+    mode = str(mcp.get("mode", "direct") or "direct").strip().lower()
+    if mode not in {"direct", "proxy"}:
+        mode = "direct"
+    return {"mode": mode}
+
+
+# ─── Delegate Defaults ────────────────────────────────────
+
+DELEGATE_DEFAULTS = {
+    "enabled": True,
+    "preferred_model": "",           # Empty = auto-select per task type
+    "allow_model_fallback": True,    # If preferred/default missing, pick best available local model
+    "fallback_models": [],           # Optional ordered list of fallback model names
+    "max_tokens": 512,
+    "temperature": 0.3,
+    "auto_compress": True,           # Auto-compress file_path content as context
+    "auto_search": True,             # Auto-search index for 'ask' tasks
+    "auto_vector_search": True,      # Auto-search vector store if available
+    "auto_activity_log": True,       # Auto-inject recent activity for diagnose
+    "search_top_k": 2,
+    "max_context_tokens": 1400,
+    # Delegation threshold policy
+    "threshold_enabled": True,       # Token-saving mode: delegate by default once threshold is met
+    "threshold_min_total_tokens": 60,
+    "threshold_task_types": ["ask", "explain", "summarize", "improve", "docstring"],
+    "threshold_force_task_types": ["diagnose", "review", "test"],
+    # Per-task model overrides (empty = use preferred_model or task default)
+    "summarize_model": "",
+    "explain_model": "",
+    "docstring_model": "",
+    "review_model": "",
+    "ask_model": "",
+    "test_model": "",
+    "diagnose_model": "",
+    "improve_model": "",
+    # Codex CLI integration (cloud delegate backend)
+    "codex_enabled": True,               # Master switch — enable Codex as delegate backend
+    "codex_default_model": "gpt-5.3-codex-spark",  # Default Codex model
+    "codex_default_sandbox": "read-only", # Default sandbox: read-only, workspace-write, danger-full-access
+    "codex_reasoning_effort": "high",     # xhigh, high, medium, low
+    "codex_timeout": 90,                  # Subprocess timeout in seconds (idle watchdog kills MCP hangs at 20s)
+    "codex_max_context_tokens": 4000,     # Context truncation limit for Codex calls
+    "codex_task_types": ["review", "diagnose", "improve", "test"],  # Task types auto-routed to Codex
+    "codex_verify_edits": False,          # EditLedgerEnricher sends diffs to Codex for review
+    "codex_memory_bridge": True,          # Auto-extract findings from Codex into c3_memory
+    # Gemini CLI integration (cloud delegate backend)
+    "gemini_enabled": True,               # Master switch — enable Gemini as delegate backend
+    "gemini_default_model": "gemini-2.5-flash",  # Default Gemini model
+    "gemini_timeout": 45,                 # Subprocess timeout in seconds (idle watchdog kills MCP hangs at 15s)
+    "gemini_max_context_tokens": 8000,    # Context truncation limit (Gemini has large context windows)
+    "gemini_task_types": ["review", "diagnose", "improve", "test"],  # Tasks auto-routed to Gemini
+    "gemini_memory_bridge": True,         # Auto-extract findings from Gemini into c3_memory
+}
+
+
+def load_delegate_config(project_path: str) -> dict:
+    """Load delegate config from .c3/config.json, merged with defaults."""
+    config_file = Path(project_path) / ".c3" / "config.json"
+    delegate = {}
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data = json.load(f)
+            delegate = data.get("delegate", {})
+        except Exception:
+            pass
+    return {**DELEGATE_DEFAULTS, **delegate}
+
+
+def load_agent_config(project_path: str) -> dict:
+    """Load agent config from .c3/config.json, merged with AGENT_DEFAULTS."""
+    config_file = Path(project_path) / ".c3" / "config.json"
+    overrides = {}
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data = json.load(f)
+            overrides = data.get("agents", {})
+        except Exception:
+            pass
+    # Merge per-agent: defaults ← overrides
+    result = {}
+    for name, defaults in AGENT_DEFAULTS.items():
+        result[name] = {**defaults, **overrides.get(name, {})}
+    return result

core/ide.py

@@ -0,0 +1,188 @@
+"""IDE Profile Registry for cross-IDE MCP support.
+
+Defines profiles for each supported IDE with their config paths, capabilities,
+and instructions file locations. Enables graceful degradation of Claude-specific
+features in non-Claude IDEs.
+"""
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class IDEProfile:
+    """Describes an IDE's MCP configuration requirements and capabilities."""
+    name: str                              # "claude-code", "vscode", "cursor", "codex"
+    display_name: str                      # "Claude Code", "VS Code Copilot"
+    config_path: str                       # ".mcp.json", ".vscode/mcp.json"
+    config_key: str                        # "mcpServers", "servers", or "mcp_servers"
+    needs_type_field: bool                 # VS Code requires "type": "stdio"
+    instructions_file: Optional[str]       # "CLAUDE.md", ".github/copilot-instructions.md"
+    instructions_line_limit: Optional[int] # 200 for Claude, None for others
+    supports_hooks: bool                   # Only Claude Code
+    supports_transcripts: bool             # Only Claude Code (reads ~/.claude/)
+    supports_clear: bool                   # Only Claude Code has /clear
+    settings_path: Optional[str]           # ".claude/settings.local.json" or None
+    config_format: str = "json"            # "json" or "toml"
+    config_path_global: bool = False       # True = config_path resolved from home dir, not project
+    hook_event: str = "PostToolUse"        # Claude="PostToolUse", Gemini="AfterTool"
+
+
+# ─── IDE Profiles ─────────────────────────────────────────
+
+PROFILES = {
+    "claude-code": IDEProfile(
+        name="claude-code",
+        display_name="Claude Code",
+        config_path=".mcp.json",
+        config_key="mcpServers",
+        needs_type_field=False,
+        instructions_file="CLAUDE.md",
+        instructions_line_limit=200,
+        supports_hooks=True,
+        supports_transcripts=True,
+        supports_clear=True,
+        settings_path=".claude/settings.local.json",
+    ),
+    "vscode": IDEProfile(
+        name="vscode",
+        display_name="VS Code Copilot",
+        config_path=".vscode/mcp.json",
+        config_key="servers",
+        needs_type_field=True,
+        instructions_file=".github/copilot-instructions.md",
+        instructions_line_limit=None,
+        supports_hooks=False,
+        supports_transcripts=False,
+        supports_clear=False,
+        settings_path=None,
+    ),
+    "cursor": IDEProfile(
+        name="cursor",
+        display_name="Cursor",
+        config_path=".cursor/mcp.json",
+        config_key="mcpServers",
+        needs_type_field=False,
+        instructions_file=".cursorrules",
+        instructions_line_limit=None,
+        supports_hooks=False,
+        supports_transcripts=False,
+        supports_clear=False,
+        settings_path=None,
+    ),
+    "codex": IDEProfile(
+        name="codex",
+        display_name="OpenAI Codex",
+        config_path=".codex/config.toml",  # project-scoped; global is ~/.codex/config.toml
+        config_key="mcp_servers",           # TOML: [mcp_servers.<name>]
+        needs_type_field=False,
+        instructions_file="AGENTS.md",
+        instructions_line_limit=None,
+        supports_hooks=False,
+        supports_transcripts=False,
+        supports_clear=False,
+        settings_path=None,
+        config_format="toml",
+    ),
+    "gemini": IDEProfile(
+        name="gemini",
+        display_name="Gemini CLI",
+        config_path=".gemini/settings.json",  # project-scoped; global is ~/.gemini/settings.json
+        config_key="mcpServers",
+        needs_type_field=False,
+        instructions_file="GEMINI.md",
+        instructions_line_limit=None,
+        supports_hooks=True,
+        supports_transcripts=False,
+        supports_clear=False,
+        settings_path=".gemini/settings.json",  # same file as MCP config
+        hook_event="AfterTool",
+    ),
+    "antigravity": IDEProfile(
+        name="antigravity",
+        display_name="Google Antigravity",
+        config_path=".gemini/antigravity/mcp_config.json",  # resolved from home dir
+        config_key="mcpServers",
+        needs_type_field=False,
+        instructions_file="GEMINI.md",
+        instructions_line_limit=None,
+        supports_hooks=False,
+        supports_transcripts=False,
+        supports_clear=False,
+        settings_path=None,
+        config_path_global=True,  # ~/.gemini/antigravity/mcp_config.json
+    ),
+}
+
+
+IDE_ALIASES = {
+    "claude": "claude-code",
+    "claude-code": "claude-code",
+}
+
+
+def normalize_ide_name(ide_name: str | None) -> str:
+    """Normalize external IDE names and aliases to canonical profile keys."""
+    raw = (ide_name or "").strip().lower()
+    if not raw:
+        return "claude-code"
+    return IDE_ALIASES.get(raw, raw)
+
+
+def get_profile(ide_name: str) -> IDEProfile:
+    """Get IDE profile by name. Returns claude-code profile if unknown."""
+    return PROFILES.get(normalize_ide_name(ide_name), PROFILES["claude-code"])
+
+
+def detect_ide(project_path: str) -> str:
+    """Auto-detect IDE from project directory markers.
+    Prioritizes explicit IDE folders over general .mcp.json to avoid mis-detection.
+    """
+    p = Path(project_path)
+
+    # 1. Direct config matches (strongest)
+    if (p / ".vscode" / "mcp.json").exists():
+        return "vscode"
+    if (p / ".cursor" / "mcp.json").exists():
+        return "cursor"
+    if (p / ".codex" / "config.toml").exists():
+        return "codex"
+    if (p / ".gemini" / "settings.json").exists():
+        # Prefer antigravity if its user-global dir already exists
+        if (Path.home() / ".gemini" / "antigravity").is_dir():
+            return "antigravity"
+        return "gemini"
+
+    # 2. IDE directory markers (even without config yet)
+    if (p / ".codex").is_dir():
+        return "codex"
+    if (p / ".gemini").is_dir():
+        if (Path.home() / ".gemini" / "antigravity").is_dir():
+            return "antigravity"
+        return "gemini"
+    if (p / ".vscode").is_dir():
+        return "vscode"
+    if (p / ".cursor").is_dir():
+        return "cursor"
+
+    # 3. Fallback to Claude markers
+    if (p / ".claude").is_dir() or (p / ".mcp.json").exists():
+        return "claude-code"
+
+    return "claude-code"
+
+
+def load_ide_config(project_path: str) -> str:
+    """Read 'ide' from .c3/config.json. Returns 'claude-code' if not set."""
+    config_file = Path(project_path) / ".c3" / "config.json"
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data = json.load(f)
+            ide = normalize_ide_name(data.get("ide", "claude-code"))
+            if ide in PROFILES:
+                return ide
+        except Exception:
+            pass
+    return "claude-code"

oracle/__init__.py

@@ -0,0 +1 @@
+"""Oracle — Cross-project memory management agent for C3."""

oracle/config.py

@@ -0,0 +1,75 @@
+"""Oracle configuration loader."""
+
+import json
+from pathlib import Path
+
+ORACLE_DIR = Path.home() / ".c3" / "oracle"
+
+CONFIG_FILE = ORACLE_DIR / "config.json"
+
+DEFAULTS = {
+    "port": 3331,
+    "ollama_base_url": "https://ollama.com",
+    "ollama_api_key": "",
+    "model": "gemma4:31b-cloud",
+    "hub_url": "http://localhost:3330",
+    "review_interval_seconds": 1800,
+    "review_enabled": True,
+    "auto_open_browser": True,
+    "theme": "dark",
+    "max_facts_per_analysis": 100,
+    "insight_confidence_threshold": 0.5,
+    "log_level": "INFO",
+    "federated_graph_ttl_sec": 3600,
+    "cross_sim_threshold": 0.75,
+    "cross_max_facts_per_project": 200,
+    "cross_top_k_neighbors": 3,
+    "embedding_model": "nomic-embed-text",
+    "agents": [
+        {
+            "id": "architect",
+            "name": "Architect",
+            "description": "Expert in system architecture, design patterns, and cross-project structure. Best for high-level analysis.",
+            "system_prompt": "You are the Architect. Focus on structural integrity, design patterns, and the big picture. Provide high-level recommendations before diving into code.",
+            "model": "gemma4:31b-cloud",
+            "active": True
+        },
+        {
+            "id": "code_explorer",
+            "name": "Code Explorer",
+            "description": "Specializes in deep code analysis, bug hunting, and tracing execution paths.",
+            "system_prompt": "You are the Code Explorer. Be incredibly precise, cite specific lines of code, and focus on the technical implementation details. Trace logic thoroughly.",
+            "model": "gemma4:31b-cloud",
+            "active": True
+        },
+        {
+            "id": "memory_analyst",
+            "name": "Memory Analyst",
+            "description": "Focuses on analyzing project memory, facts, and insights.",
+            "system_prompt": "You are the Memory Analyst. Rely heavily on memory tools and facts to spot trends. Connect current issues to past context.",
+            "model": "gemma4:31b-cloud",
+            "active": True
+        }
+    ],
+}
+
+
+def load_config() -> dict:
+    """Load Oracle config, merged with defaults."""
+    cfg = dict(DEFAULTS)
+    try:
+        if CONFIG_FILE.exists():
+            with open(CONFIG_FILE, encoding="utf-8") as f:
+                cfg.update(json.load(f))
+    except Exception:
+        pass
+    return cfg
+
+
+def save_config(cfg: dict):
+    """Write Oracle config to disk."""
+    ORACLE_DIR.mkdir(parents=True, exist_ok=True)
+    merged = dict(DEFAULTS)
+    merged.update(cfg)
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(merged, f, indent=2)