algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/intelligence/structural_validator.py

@@ -0,0 +1,148 @@
+"""B78. Incremental Structural Validation.
+
+Validate code changes in <200ms using tree-sitter-style AST checks.
+3-tier resolution.  Circuit breaker for false positives.
+Source: Keel pattern.
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Severity(Enum):
+    ERROR = "ERROR"
+    WARNING = "WARNING"
+    INFO = "INFO"
+
+
+@dataclass
+class Violation:
+    code: str
+    severity: Severity
+    symbol: str
+    file: str
+    line: int
+    message: str
+    fix_hint: str = ""
+
+
+class CircuitBreaker:
+    """Auto-downgrade repeated false positives to warnings."""
+
+    def __init__(self, max_failures: int = 3) -> None:
+        self._counts: dict[str, int] = {}
+        self._max = max_failures
+
+    def check(self, violation: Violation) -> Violation:
+        if violation.severity == Severity.ERROR:
+            key = f"{violation.code}:{violation.symbol}"
+            self._counts[key] = self._counts.get(key, 0) + 1
+            if self._counts[key] >= self._max:
+                violation.severity = Severity.WARNING
+        return violation
+
+    def reset(self) -> None:
+        self._counts.clear()
+
+
+class StructuralValidator:
+    """Validate Python code structure using AST."""
+
+    ERROR_CODES = {
+        "E001": "Symbol referenced but not found",
+        "E002": "Missing type hints",
+        "E003": "Missing docstring",
+        "E004": "Function removed but still referenced",
+        "E005": "Arity mismatch",
+        "W001": "Symbol in wrong module",
+        "W002": "Duplicate name across modules",
+    }
+
+    def __init__(self) -> None:
+        self._breaker = CircuitBreaker()
+        self._defined_names: dict[str, str] = {}  # name → file
+        self._referenced_names: set[str] = set()
+
+    def compile_file(self, filepath: str, content: str) -> list[Violation]:
+        """Validate a single file. Returns violations."""
+        violations: list[Violation] = []
+
+        try:
+            tree = ast.parse(content, filename=filepath)
+        except SyntaxError as e:
+            violations.append(Violation(
+                code="E001", severity=Severity.ERROR,
+                symbol="<syntax>", file=filepath, line=e.lineno or 0,
+                message=f"Syntax error: {e.msg}",
+                fix_hint="Fix the syntax error",
+            ))
+            return violations
+
+        # Collect defined names
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                self._defined_names[node.name] = filepath
+                # Check for type hints
+                if not node.returns and not any(a.annotation for a in node.args.args):
+                    violations.append(Violation(
+                        code="E002", severity=Severity.WARNING,
+                        symbol=node.name, file=filepath, line=node.lineno,
+                        message="Missing type hints",
+                        fix_hint="Add type annotations",
+                    ))
+                # Check for docstring
+                if not ast.get_docstring(node):
+                    violations.append(Violation(
+                        code="E003", severity=Severity.INFO,
+                        symbol=node.name, file=filepath, line=node.lineno,
+                        message="Missing docstring",
+                        fix_hint="Add a docstring",
+                    ))
+            elif isinstance(node, ast.ClassDef):
+                self._defined_names[node.name] = filepath
+
+        # Collect referenced names
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                if isinstance(node.func, ast.Name):
+                    self._referenced_names.add(node.func.name)
+
+        # Check for broken callers
+        for ref in self._referenced_names:
+            if ref not in self._defined_names and not ref.startswith("_"):
+                # Only flag if it looks like a local reference
+                pass  # Could be built-in or import
+
+        # Apply circuit breaker
+        violations = [self._breaker.check(v) for v in violations]
+        return violations
+
+    def check_broken_callers(self, removed_name: str) -> list[Violation]:
+        """Check if a removed function is still referenced."""
+        if removed_name in self._referenced_names:
+            return [Violation(
+                code="E004", severity=Severity.ERROR,
+                symbol=removed_name, file="<unknown>", line=0,
+                message=f"Function '{removed_name}' removed but still referenced",
+                fix_hint="Update callers or restore function",
+            )]
+        return []
+
+    def find_duplicates(self) -> list[Violation]:
+        """Find duplicate names across modules."""
+        name_to_files: dict[str, list[str]] = {}
+        for name, filepath in self._defined_names.items():
+            name_to_files.setdefault(name, []).append(filepath)
+
+        violations: list[Violation] = []
+        for name, files in name_to_files.items():
+            if len(set(files)) > 1:
+                violations.append(Violation(
+                    code="W002", severity=Severity.WARNING,
+                    symbol=name, file=files[0], line=0,
+                    message=f"Duplicate name '{name}' in {len(set(files))} files",
+                    fix_hint="Rename to avoid confusion",
+                ))
+        return violations

algo_cli/intelligence/subagent_spawner.py

@@ -0,0 +1,111 @@
+"""B69. Sub-Agent Spawning with Virtual File Isolation.
+
+Spawn focused sub-agents with fresh context, explicit file passing,
+and tool scoping.  Source: Sub-Agent-MCP pattern.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Callable
+
+
+class AgentState(Enum):
+    PENDING = auto()
+    RUNNING = auto()
+    DONE = auto()
+    FAILED = auto()
+    CANCELLED = auto()
+
+
+@dataclass
+class SubAgentConfig:
+    id: str
+    name: str
+    system_prompt: str = ""
+    model: str = ""  # empty = use parent's model
+    allowed_tools: list[str] = field(default_factory=list)
+    allowed_files: list[str] = field(default_factory=list)  # explicit file passing
+    max_iterations: int = 5
+    timeout_s: float = 60.0
+
+
+@dataclass
+class SubAgentResult:
+    agent_id: str
+    state: AgentState = AgentState.PENDING
+    output: str = ""
+    files_read: list[str] = field(default_factory=list)
+    files_written: list[str] = field(default_factory=list)
+    tool_calls: int = 0
+    duration_s: float = 0.0
+    error: str | None = None
+
+
+class SubAgentSpawner:
+    """Spawn sub-agents with virtual file isolation."""
+
+    def __init__(self) -> None:
+        self._configs: dict[str, SubAgentConfig] = {}
+        self._results: dict[str, SubAgentResult] = {}
+        self._active: dict[str, SubAgentResult] = {}
+
+    def register(self, config: SubAgentConfig) -> None:
+        self._configs[config.id] = config
+
+    def spawn(self, agent_id: str, task: str,
+              run_fn: Callable[[SubAgentConfig, str], str] | None = None) -> SubAgentResult:
+        config = self._configs.get(agent_id)
+        if not config:
+            raise KeyError(f"Agent {agent_id} not registered")
+
+        result = SubAgentResult(agent_id=agent_id, state=AgentState.RUNNING)
+        self._active[agent_id] = result
+        start = time.time()
+
+        try:
+            if run_fn:
+                output = run_fn(config, task)
+            else:
+                output = f"[{config.name}: {task}]"
+            result.output = output
+            result.state = AgentState.DONE
+        except Exception as e:
+            result.error = str(e)
+            result.state = AgentState.FAILED
+        finally:
+            result.duration_s = time.time() - start
+            self._results[agent_id] = result
+            self._active.pop(agent_id, None)
+
+        return result
+
+    def cancel(self, agent_id: str) -> bool:
+        result = self._active.get(agent_id)
+        if result and result.state == AgentState.RUNNING:
+            result.state = AgentState.CANCELLED
+            return True
+        return False
+
+    def get_result(self, agent_id: str) -> SubAgentResult | None:
+        return self._results.get(agent_id)
+
+    def list_active(self) -> list[str]:
+        return [aid for aid, r in self._active.items() if r.state == AgentState.RUNNING]
+
+    def can_access_file(self, agent_id: str, file_path: str) -> bool:
+        config = self._configs.get(agent_id)
+        if not config:
+            return False
+        if not config.allowed_files:
+            return True  # no restriction
+        return file_path in config.allowed_files
+
+    def can_use_tool(self, agent_id: str, tool_name: str) -> bool:
+        config = self._configs.get(agent_id)
+        if not config:
+            return False
+        if not config.allowed_tools:
+            return True
+        return tool_name in config.allowed_tools

algo_cli/intelligence/symmetric_verify.py

@@ -0,0 +1,70 @@
+"""H14 — Symmetric Encode/Decode Verification.
+
+Every creator pattern needs a verifier companion.
+Mined from ST3GG dual-use design.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SymmetricPair:
+    """A creator/verifier pair of algorithm entries."""
+
+    creator_id: str
+    verifier_id: str
+    creator_title: str = ""
+    verifier_title: str = ""
+    metadata: dict[str, field] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "creator_id": self.creator_id,
+            "verifier_id": self.verifier_id,
+            "creator_title": self.creator_title,
+            "verifier_title": self.verifier_title,
+        }
+
+
+class SymmetricVerifier:
+    """Check that every creator entry has a matching verifier entry."""
+
+    def __init__(self) -> None:
+        self._pairs: list[SymmetricPair] = []
+
+    def register(
+        self,
+        creator_id: str,
+        verifier_id: str,
+        creator_title: str = "",
+        verifier_title: str = "",
+    ) -> SymmetricPair:
+        pair = SymmetricPair(
+            creator_id=creator_id,
+            verifier_id=verifier_id,
+            creator_title=creator_title,
+            verifier_title=verifier_title,
+        )
+        self._pairs.append(pair)
+        return pair
+
+    def check_symmetry(self, entry_ids: set[str]) -> list[str]:
+        """Return list of unpaired creator IDs."""
+        missing = []
+        for pair in self._pairs:
+            if pair.creator_id in entry_ids and pair.verifier_id not in entry_ids:
+                missing.append(pair.creator_id)
+        return missing
+
+    def get_pairs(self) -> list[SymmetricPair]:
+        return list(self._pairs)
+
+    def count(self) -> int:
+        return len(self._pairs)
+
+    def find_pair(self, creator_id: str) -> SymmetricPair | None:
+        for pair in self._pairs:
+            if pair.creator_id == creator_id:
+                return pair
+        return None

algo_cli/intelligence/task_classifier.py

@@ -0,0 +1,129 @@
+"""B84. Task Classifier + Agent Delegator.
+
+Classify tasks by complexity/domain.  Route to appropriate agents.
+Source: CCASP pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Callable
+
+
+class TaskComplexity(Enum):
+    TRIVIAL = auto()     # read, list, search — cheap model
+    SIMPLE = auto()     # single edit, single test — standard model
+    MODERATE = auto()    # multi-file edit, fix bug — standard model
+    COMPLEX = auto()    # refactor, new feature — expensive model
+    CRITICAL = auto()   # architecture, security — expensive model + review
+
+
+class TaskDomain(Enum):
+    CODE = auto()
+    RESEARCH = auto()
+    MAINTENANCE = auto()
+    DOCUMENTATION = auto()
+    TESTING = auto()
+    DEPLOYMENT = auto()
+    UNKNOWN = auto()
+
+
+@dataclass
+class TaskClassification:
+    complexity: TaskComplexity
+    domain: TaskDomain
+    confidence: float = 0.5
+    suggested_model: str = ""
+    suggested_agents: list[str] = field(default_factory=list)
+    estimated_steps: int = 1
+
+
+COMPLEXITY_KEYWORDS: dict[TaskComplexity, list[str]] = {
+    TaskComplexity.TRIVIAL: ["read", "list", "show", "find", "search", "grep", "where"],
+    TaskComplexity.SIMPLE: ["fix", "update", "rename", "add", "remove", "change"],
+    TaskComplexity.MODERATE: ["refactor", "migrate", "convert", "split", "merge"],
+    TaskComplexity.COMPLEX: ["implement", "design", "architect", "create new", "build"],
+    TaskComplexity.CRITICAL: ["security", "deploy", "release", "migration", "rewrite"],
+}
+
+DOMAIN_KEYWORDS: dict[TaskDomain, list[str]] = {
+    TaskDomain.CODE: ["function", "class", "method", "variable", "import", "module"],
+    TaskDomain.RESEARCH: ["research", "analyze", "compare", "investigate", "survey"],
+    TaskDomain.MAINTENANCE: ["maintain", "clean", "update", "upgrade", "fix"],
+    TaskDomain.DOCUMENTATION: ["document", "readme", "doc", "comment", "explain"],
+    TaskDomain.TESTING: ["test", "spec", "coverage", "mock", "fixture"],
+    TaskDomain.DEPLOYMENT: ["deploy", "release", "publish", "ci", "cd", "build"],
+}
+
+MODEL_BY_COMPLEXITY: dict[TaskComplexity, str] = {
+    TaskComplexity.TRIVIAL: "qwen3:4b",
+    TaskComplexity.SIMPLE: "glm-5.2",
+    TaskComplexity.MODERATE: "glm-5.2",
+    TaskComplexity.COMPLEX: "gpt-5.5",
+    TaskComplexity.CRITICAL: "gpt-5.5",
+}
+
+
+class TaskClassifier:
+    """Classify tasks by complexity and domain."""
+
+    def classify(self, task_description: str) -> TaskClassification:
+        desc_lower = task_description.lower()
+
+        # Determine complexity
+        complexity_scores: dict[TaskComplexity, int] = {}
+        for comp, keywords in COMPLEXITY_KEYWORDS.items():
+            score = sum(1 for kw in keywords if kw in desc_lower)
+            complexity_scores[comp] = score
+
+        complexity = max(complexity_scores, key=complexity_scores.get)
+        if complexity_scores[complexity] == 0:
+            complexity = TaskComplexity.SIMPLE  # default
+
+        # Determine domain
+        domain_scores: dict[TaskDomain, int] = {}
+        for domain, keywords in DOMAIN_KEYWORDS.items():
+            score = sum(1 for kw in keywords if kw in desc_lower)
+            domain_scores[domain] = score
+
+        domain = max(domain_scores, key=domain_scores.get)
+        if domain_scores[domain] == 0:
+            domain = TaskDomain.UNKNOWN
+
+        # Estimate steps
+        step_count = desc_lower.count(" and ") + desc_lower.count(" then ") + 1
+        step_count = min(step_count, 10)
+
+        # Confidence based on keyword match strength
+        total_matches = sum(complexity_scores.values()) + sum(domain_scores.values())
+        confidence = min(1.0, total_matches / 5.0)
+
+        return TaskClassification(
+            complexity=complexity,
+            domain=domain,
+            confidence=confidence,
+            suggested_model=MODEL_BY_COMPLEXITY[complexity],
+            estimated_steps=step_count,
+        )
+
+
+class AgentDelegator:
+    """Route classified tasks to appropriate agents."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[TaskDomain, Callable[[str, TaskClassification], str]] = {}
+        self._classifier = TaskClassifier()
+
+    def register_handler(self, domain: TaskDomain,
+                          handler: Callable[[str, TaskClassification], str]) -> None:
+        self._handlers[domain] = handler
+
+    def delegate(self, task: str) -> tuple[TaskClassification, str]:
+        """Classify and delegate a task. Returns (classification, result)."""
+        classification = self._classifier.classify(task)
+        handler = self._handlers.get(classification.domain)
+        if handler:
+            result = handler(task, classification)
+        else:
+            result = f"No handler for domain {classification.domain.name}"
+        return classification, result

algo_cli/intelligence/team_execution.py

@@ -0,0 +1,122 @@
+"""B72. Team Execution: ALL vs RACE Strategies.
+
+ALL: wait for all agents, compare results.
+RACE: first-success wins with atomic lock.
+Input sharding: split input across agents.
+Source: gecko pattern.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Callable
+
+
+class TeamStrategy(Enum):
+    ALL = auto()   # wait for all, compare
+    RACE = auto()  # first success wins
+
+
+@dataclass
+class TeamMember:
+    agent_id: str
+    model: str = ""
+    role: str = "worker"
+
+
+@dataclass
+class TeamResult:
+    strategy: TeamStrategy
+    results: dict[str, Any] = field(default_factory=dict)  # agent_id → output
+    winner: str | None = None
+    errors: dict[str, str] = field(default_factory=dict)
+    duration_s: float = 0.0
+
+
+class TeamExecutor:
+    """Execute tasks across a team of agents with ALL or RACE strategy."""
+
+    def __init__(self, members: list[TeamMember]) -> None:
+        self._members = {m.agent_id: m for m in members}
+        self._lock = threading.Lock()
+
+    def execute_all(
+        self,
+        task: str,
+        run_fn: Callable[[str, str], Any],  # (agent_id, task) → output
+        timeout: float = 60.0,
+    ) -> TeamResult:
+        """ALL strategy: run all agents, wait for all, return all results."""
+        result = TeamResult(strategy=TeamStrategy.ALL)
+        start = time.time()
+        threads: list[threading.Thread] = []
+
+        def worker(agent_id: str) -> None:
+            try:
+                output = run_fn(agent_id, task)
+                with self._lock:
+                    result.results[agent_id] = output
+            except Exception as e:
+                with self._lock:
+                    result.errors[agent_id] = str(e)
+
+        for member_id in self._members:
+            t = threading.Thread(target=worker, args=(member_id,))
+            threads.append(t)
+            t.start()
+
+        for t in threads:
+            t.join(timeout=timeout)
+
+        result.duration_s = time.time() - start
+        return result
+
+    def execute_race(
+        self,
+        task: str,
+        run_fn: Callable[[str, str], Any],
+        timeout: float = 60.0,
+    ) -> TeamResult:
+        """RACE strategy: first agent to succeed wins."""
+        result = TeamResult(strategy=TeamStrategy.RACE)
+        start = time.time()
+        won = threading.Event()
+
+        def worker(agent_id: str) -> None:
+            if won.is_set():
+                return
+            try:
+                output = run_fn(agent_id, task)
+                with self._lock:
+                    if not won.is_set():
+                        result.results[agent_id] = output
+                        result.winner = agent_id
+                        won.set()
+            except Exception as e:
+                with self._lock:
+                    result.errors[agent_id] = str(e)
+
+        threads: list[threading.Thread] = []
+        for member_id in self._members:
+            t = threading.Thread(target=worker, args=(member_id,))
+            threads.append(t)
+            t.start()
+
+        won.wait(timeout=timeout)
+        for t in threads:
+            t.join(timeout=1.0)
+
+        result.duration_s = time.time() - start
+        return result
+
+    def shard_input(self, items: list[Any], num_shards: int | None = None) -> list[list[Any]]:
+        """Split input items across team members."""
+        n = num_shards or len(self._members)
+        if n <= 0:
+            return [items]
+        shards: list[list[Any]] = [[] for _ in range(n)]
+        for i, item in enumerate(items):
+            shards[i % n].append(item)
+        return [s for s in shards if s]

algo_cli/intelligence/tiered_access.py

@@ -0,0 +1,121 @@
+"""H31 — Tiered Tool Access.
+
+Default / opt-in / approval-gated tool tiers.
+Mined from T3MP3ST FEATURES.md §6.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class AccessTier(str, Enum):
+    DEFAULT = "default"
+    OPT_IN = "opt_in"
+    APPROVAL_GATED = "approval_gated"
+
+
+@dataclass
+class TierConfig:
+    """Configuration for a tool's access tier."""
+
+    tool_name: str
+    tier: AccessTier
+    env_var: str = ""
+    requires_approval: bool = False
+    description: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tool_name": self.tool_name,
+            "tier": self.tier.value,
+            "env_var": self.env_var,
+            "requires_approval": self.requires_approval,
+            "description": self.description,
+        }
+
+
+@dataclass
+class AccessResult:
+    """Result of an access check."""
+
+    granted: bool
+    reason: str = ""
+    required_tier: AccessTier = AccessTier.DEFAULT
+    missing_env_var: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "granted": self.granted,
+            "reason": self.reason,
+            "required_tier": self.required_tier.value,
+            "missing_env_var": self.missing_env_var,
+        }
+
+
+class TieredAccessGate:
+    """Check tool access against tiered configuration."""
+
+    def __init__(self) -> None:
+        self._configs: dict[str, TierConfig] = {}
+
+    def register(
+        self,
+        tool_name: str,
+        tier: AccessTier,
+        env_var: str = "",
+        requires_approval: bool = False,
+        description: str = "",
+    ) -> TierConfig:
+        config = TierConfig(
+            tool_name=tool_name,
+            tier=tier,
+            env_var=env_var,
+            requires_approval=requires_approval,
+            description=description,
+        )
+        self._configs[tool_name] = config
+        return config
+
+    def check(self, tool_name: str, approved: bool = False) -> AccessResult:
+        config = self._configs.get(tool_name)
+        if config is None:
+            return AccessResult(granted=True, reason="No tier config — default allow")
+        if config.tier == AccessTier.DEFAULT:
+            return AccessResult(granted=True, reason="Default tier — always allowed")
+        if config.tier == AccessTier.OPT_IN:
+            if config.env_var and not os.environ.get(config.env_var):
+                return AccessResult(
+                    granted=False,
+                    reason=f"Opt-in tool requires env var {config.env_var}",
+                    required_tier=AccessTier.OPT_IN,
+                    missing_env_var=config.env_var,
+                )
+            return AccessResult(granted=True, reason="Opt-in env var set")
+        if config.tier == AccessTier.APPROVAL_GATED:
+            if config.env_var and not os.environ.get(config.env_var):
+                return AccessResult(
+                    granted=False,
+                    reason=f"Approval-gated tool requires env var {config.env_var}",
+                    required_tier=AccessTier.APPROVAL_GATED,
+                    missing_env_var=config.env_var,
+                )
+            if not approved:
+                return AccessResult(
+                    granted=False,
+                    reason="Approval-gated tool requires explicit approval",
+                    required_tier=AccessTier.APPROVAL_GATED,
+                )
+            return AccessResult(granted=True, reason="Approved and env var set")
+        return AccessResult(granted=False, reason="Unknown tier")
+
+    def get_config(self, tool_name: str) -> TierConfig | None:
+        return self._configs.get(tool_name)
+
+    def all_configs(self) -> list[TierConfig]:
+        return list(self._configs.values())
+
+    def count(self) -> int:
+        return len(self._configs)