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

algo_cli/intelligence/shell_session.py

@@ -0,0 +1,213 @@
+"""B41. Pseudoterminal Boundary + VT Parser/Emitter (Windows Terminal Pattern).
+
+Wraps shell command execution with a session abstraction: process boundary,
+streaming stdout/stderr frames, ANSI/VT normalization, command replay
+metadata, and timeout/cancellation.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ── ANSI/VT normalization ─────────────────────────────────────────────
+
+# Match ANSI escape sequences
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+# Match other control chars (except \n, \r, \t)
+_CTRL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f]")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences."""
+    return _ANSI_RE.sub("", text)
+
+
+def normalize_vt(text: str) -> str:
+    """Remove ANSI escapes and control characters, keep newlines/tabs."""
+    text = _ANSI_RE.sub("", text)
+    text = _CTRL_RE.sub("", text)
+    return text
+
+
+def has_ansi(text: str) -> bool:
+    """Check if text contains ANSI escape sequences."""
+    return bool(_ANSI_RE.search(text))
+
+
+# ── streaming frames ──────────────────────────────────────────────────
+
+
+@dataclass
+class OutputFrame:
+    """A single chunk of process output."""
+    stream: str  # "stdout" or "stderr"
+    data: str
+    raw_bytes: bytes = b""
+    timestamp: float = field(default_factory=time.time)
+    frame_index: int = 0
+
+
+@dataclass
+class CommandRecord:
+    """Metadata for a executed command (for replay)."""
+    id: str
+    command: str
+    cwd: str = ""
+    started_at: float = field(default_factory=time.time)
+    finished_at: float | None = None
+    exit_code: int | None = None
+    frames: list[OutputFrame] = field(default_factory=list)
+    cancelled: bool = False
+    timeout_hit: bool = False
+
+    @property
+    def duration_ms(self) -> float:
+        end = self.finished_at or time.time()
+        return (end - self.started_at) * 1000
+
+    @property
+    def raw_output(self) -> str:
+        """Raw output with ANSI preserved."""
+        return "".join(f.data for f in self.frames)
+
+    @property
+    def normalized_output(self) -> str:
+        """Output with ANSI/control chars stripped."""
+        return normalize_vt(self.raw_output)
+
+    @property
+    def stdout(self) -> str:
+        return normalize_vt("".join(f.data for f in self.frames if f.stream == "stdout"))
+
+    @property
+    def stderr(self) -> str:
+        return normalize_vt("".join(f.data for f in self.frames if f.stream == "stderr"))
+
+
+# ── shell session ─────────────────────────────────────────────────────
+
+
+class ShellSession:
+    """Pseudoterminal boundary for shell command execution.
+
+    Wraps subprocess execution with:
+    - streaming output frames
+    - raw + normalized output preservation
+    - timeout/cancellation
+    - command replay metadata
+    - ANSI/VT normalization
+    """
+
+    def __init__(self, cwd: str = "", default_timeout: int = 120):
+        self.cwd = cwd
+        self.default_timeout = default_timeout
+        self.history: list[CommandRecord] = []
+        self._cancelled_ids: set[str] = set()
+
+    def execute(self, command: str, timeout: int | None = None) -> CommandRecord:
+        """Execute a command and return its record.
+
+        This is a synchronous wrapper. For real streaming, use execute_streaming.
+        """
+        import subprocess
+
+        rec = CommandRecord(id=str(uuid.uuid4()), command=command, cwd=self.cwd)
+        effective_timeout = timeout or self.default_timeout
+
+        try:
+            proc = subprocess.run(
+                command,
+                cwd=self.cwd or None,
+                capture_output=True,
+                text=True,
+                timeout=effective_timeout,
+                shell=True,
+            )
+            rec.frames.append(OutputFrame(
+                stream="stdout", data=proc.stdout,
+                raw_bytes=proc.stdout.encode("utf-8", errors="replace"),
+                frame_index=0,
+            ))
+            rec.frames.append(OutputFrame(
+                stream="stderr", data=proc.stderr,
+                raw_bytes=proc.stderr.encode("utf-8", errors="replace"),
+                frame_index=1,
+            ))
+            rec.exit_code = proc.returncode
+            rec.finished_at = time.time()
+        except subprocess.TimeoutExpired as e:
+            rec.timeout_hit = True
+            rec.exit_code = -1
+            rec.finished_at = time.time()
+            if e.stdout:
+                rec.frames.append(OutputFrame(stream="stdout", data=e.stdout.decode("utf-8", errors="replace") if isinstance(e.stdout, bytes) else str(e.stdout), frame_index=0))
+            if e.stderr:
+                rec.frames.append(OutputFrame(stream="stderr", data=e.stderr.decode("utf-8", errors="replace") if isinstance(e.stderr, bytes) else str(e.stderr), frame_index=1))
+        except Exception as e:
+            rec.exit_code = -1
+            rec.finished_at = time.time()
+            rec.frames.append(OutputFrame(stream="stderr", data=str(e), frame_index=0))
+
+        self.history.append(rec)
+        return rec
+
+    def cancel(self, command_id: str) -> None:
+        """Mark a command as cancelled (for async execution)."""
+        self._cancelled_ids.add(command_id)
+
+    def is_cancelled(self, command_id: str) -> bool:
+        return command_id in self._cancelled_ids
+
+    def replay(self, command_id: str) -> CommandRecord | None:
+        """Get a past command record for replay/inspection."""
+        for rec in self.history:
+            if rec.id == command_id:
+                return rec
+        return None
+
+    def recent(self, n: int = 10) -> list[CommandRecord]:
+        """Get the N most recent command records."""
+        return self.history[-n:]
+
+    def stats(self) -> dict[str, Any]:
+        total = len(self.history)
+        succeeded = sum(1 for r in self.history if r.exit_code == 0)
+        failed = sum(1 for r in self.history if r.exit_code is not None and r.exit_code != 0)
+        timeouts = sum(1 for r in self.history if r.timeout_hit)
+        return {
+            "total": total,
+            "succeeded": succeeded,
+            "failed": failed,
+            "timeouts": timeouts,
+            "avg_duration_ms": sum(r.duration_ms for r in self.history) / max(total, 1),
+        }
+
+
+# ── shell guardrail parser ────────────────────────────────────────────
+
+
+_BLOCKED_PATTERNS = [
+    (r"<<\s*['\"]?EOF", "heredoc not supported in cmd.exe"),
+    (r"<<\s*['\"]?PY", "heredoc not supported in cmd.exe"),
+    (r"python\s+-c\s+\"[^\"]*\\n", "literal \\n in python -c not supported in cmd.exe"),
+    (r"\bcat\s+<<", "cat heredoc not supported in cmd.exe"),
+]
+
+
+def check_shell_safety(command: str, shell: str = "cmd") -> list[str]:
+    """Check a command for shell-specific safety issues.
+
+    Returns a list of warning strings (empty if safe).
+    """
+    if shell != "cmd":
+        return []
+    warnings: list[str] = []
+    for pattern, message in _BLOCKED_PATTERNS:
+        if re.search(pattern, command):
+            warnings.append(message)
+    return warnings

algo_cli/intelligence/source_registry.py

@@ -0,0 +1,143 @@
+"""B42. Source Registry + Policy-Aware Resolution (WinGet Pattern).
+
+Manages multiple harness/plugin/model/document sources with priority,
+trust levels, enabled flags, and policy locks.  Higher-priority trusted
+sources win resolution conflicts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+class SourceType:
+    HARNESS = "harness"
+    PLUGIN = "plugin"
+    MODEL = "model"
+    DOCUMENT = "document"
+    PROJECT = "project"
+    KNOWLEDGE_GRAPH = "knowledge_graph"
+
+
+@dataclass
+class Source:
+    """A registered content source."""
+
+    source_id: str
+    source_type: str
+    path: str = ""
+    priority: int = 100  # lower = higher priority
+    trust_level: str = "trusted"  # "trusted", "untrusted", "blocked"
+    enabled: bool = True
+    last_refresh: str = ""
+    policy_locked: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def can_resolve(self) -> bool:
+        return self.enabled and self.trust_level != "blocked"
+
+
+@dataclass
+class SourceRecord:
+    """A record retrieved from a source, with provenance."""
+    source_id: str
+    record_id: str
+    content: Any
+    trust_level: str = "trusted"
+
+
+class SourceRegistry:
+    """Policy-aware source registry with priority resolution."""
+
+    def __init__(self) -> None:
+        self._sources: dict[str, Source] = {}
+
+    def add(self, source: Source) -> None:
+        self._sources[source.source_id] = source
+
+    def remove(self, source_id: str) -> bool:
+        return self._sources.pop(source_id, None) is not None
+
+    def get(self, source_id: str) -> Source | None:
+        return self._sources.get(source_id)
+
+    def list_all(self) -> list[Source]:
+        return list(self._sources.values())
+
+    def list_enabled(self) -> list[Source]:
+        return [s for s in self._sources.values() if s.enabled]
+
+    def list_by_type(self, source_type: str) -> list[Source]:
+        return [s for s in self._sources.values() if s.source_type == source_type]
+
+    def resolve(self, record_id: str, candidates: list[SourceRecord]) -> SourceRecord | None:
+        """Resolve a record from multiple sources by priority/trust.
+
+        Higher-priority (lower number) trusted sources win.
+        """
+        enabled_sources = {s.source_id: s for s in self._sources.values() if s.can_resolve()}
+        best: SourceRecord | None = None
+        best_priority = 999
+        for rec in candidates:
+            src = enabled_sources.get(rec.source_id)
+            if not src:
+                continue
+            if src.priority < best_priority:
+                best = rec
+                best_priority = src.priority
+        return best
+
+    def disable(self, source_id: str) -> bool:
+        src = self._sources.get(source_id)
+        if src and not src.policy_locked:
+            src.enabled = False
+            return True
+        return False
+
+    def enable(self, source_id: str) -> bool:
+        src = self._sources.get(source_id)
+        if src:
+            src.enabled = True
+            return True
+        return False
+
+    def lock_policy(self, source_id: str) -> bool:
+        src = self._sources.get(source_id)
+        if src:
+            src.policy_locked = True
+            return True
+        return False
+
+    def refresh(self, source_id: str) -> bool:
+        src = self._sources.get(source_id)
+        if src:
+            src.last_refresh = datetime.now().isoformat()
+            return True
+        return False
+
+    def health(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "source_id": s.source_id,
+                "type": s.source_type,
+                "enabled": s.enabled,
+                "trust": s.trust_level,
+                "priority": s.priority,
+                "last_refresh": s.last_refresh,
+                "policy_locked": s.policy_locked,
+            }
+            for s in self._sources.values()
+        ]
+
+    def conflicts(self) -> list[dict[str, Any]]:
+        """Detect sources with same type and priority."""
+        by_key: dict[tuple[str, int], list[str]] = {}
+        for s in self._sources.values():
+            key = (s.source_type, s.priority)
+            by_key.setdefault(key, []).append(s.source_id)
+        return [
+            {"type": k[0], "priority": k[1], "sources": v}
+            for k, v in by_key.items() if len(v) > 1
+        ]

algo_cli/intelligence/spawn_scales.py

@@ -0,0 +1,99 @@
+"""B76. Three Scales of Spawning.
+
+Virtual File (2-4 agents) → Git Worktree (10-100) → Cloud Worker (100+).
+Source: awesome-agentic-patterns.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Any
+
+
+class SpawnScale(Enum):
+    VIRTUAL_FILE = auto()    # 2-4 agents, in-memory isolation
+    GIT_WORKTREE = auto()    # 10-100 agents, filesystem isolation
+    CLOUD_WORKER = auto()    # 100+ agents, container isolation
+
+
+@dataclass
+class ScaleConfig:
+    scale: SpawnScale
+    max_agents: int
+    isolation_level: str  # "memory", "filesystem", "container"
+    cost_per_agent: float  # relative cost
+    setup_time_s: float   # time to spawn one agent
+    cleanup_required: bool
+
+
+DEFAULT_CONFIGS: dict[SpawnScale, ScaleConfig] = {
+    SpawnScale.VIRTUAL_FILE: ScaleConfig(
+        scale=SpawnScale.VIRTUAL_FILE,
+        max_agents=4,
+        isolation_level="memory",
+        cost_per_agent=0.1,
+        setup_time_s=0.01,
+        cleanup_required=False,
+    ),
+    SpawnScale.GIT_WORKTREE: ScaleConfig(
+        scale=SpawnScale.GIT_WORKTREE,
+        max_agents=100,
+        isolation_level="filesystem",
+        cost_per_agent=0.5,
+        setup_time_s=0.5,
+        cleanup_required=True,
+    ),
+    SpawnScale.CLOUD_WORKER: ScaleConfig(
+        scale=SpawnScale.CLOUD_WORKER,
+        max_agents=1000,
+        isolation_level="container",
+        cost_per_agent=2.0,
+        setup_time_s=5.0,
+        cleanup_required=True,
+    ),
+}
+
+
+class SpawnScaleSelector:
+    """Select the appropriate spawning scale based on requirements."""
+
+    def select(self, num_agents: int, needs_filesystem: bool = False,
+               needs_network: bool = False, budget: float = 1.0) -> SpawnScale:
+        """Choose the minimal scale that meets requirements."""
+        if num_agents <= 4 and not needs_filesystem and not needs_network:
+            return SpawnScale.VIRTUAL_FILE
+        if num_agents <= 100 and not needs_network:
+            return SpawnScale.GIT_WORKTREE
+        return SpawnScale.CLOUD_WORKER
+
+    def get_config(self, scale: SpawnScale) -> ScaleConfig:
+        return DEFAULT_CONFIGS[scale]
+
+    def estimate_cost(self, scale: SpawnScale, num_agents: int) -> float:
+        config = self.get_config(scale)
+        return config.cost_per_agent * num_agents
+
+    def validate(self, scale: SpawnScale, num_agents: int) -> list[str]:
+        """Check if the scale can handle the requested agent count."""
+        issues: list[str] = []
+        config = self.get_config(scale)
+        if num_agents > config.max_agents:
+            issues.append(f"Too many agents: {num_agents} > {config.max_agents} for {scale.name}")
+        return issues
+
+    def recommend(self, num_agents: int, needs_filesystem: bool = False,
+                  needs_network: bool = False, budget: float = 1.0) -> dict[str, Any]:
+        """Get a recommendation with cost estimate."""
+        scale = self.select(num_agents, needs_filesystem, needs_network, budget)
+        config = self.get_config(scale)
+        cost = self.estimate_cost(scale, num_agents)
+        issues = self.validate(scale, num_agents)
+
+        return {
+            "scale": scale.name,
+            "isolation": config.isolation_level,
+            "estimated_cost": cost,
+            "setup_time_s": config.setup_time_s * num_agents,
+            "cleanup_required": config.cleanup_required,
+            "issues": issues,
+        }

algo_cli/intelligence/stat_stability.py

@@ -0,0 +1,104 @@
+"""H19 — Statistical Stability Guard.
+
+Warn when sample sizes are too small for stable results.
+Mined from GLOSSOPETRAE VALIDATION.md D4 (3-seed default yields ±15pt swing).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass
+class StabilityReport:
+    """Report on statistical stability of a measurement."""
+
+    sample_size: int
+    mean: float
+    std_dev: float
+    margin_of_error: float
+    confidence_level: float
+    is_stable: bool
+    recommended_sample_size: int
+    warning: str = ""
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "sample_size": self.sample_size,
+            "mean": self.mean,
+            "std_dev": self.std_dev,
+            "margin_of_error": self.margin_of_error,
+            "confidence_level": self.confidence_level,
+            "is_stable": self.is_stable,
+            "recommended_sample_size": self.recommended_sample_size,
+            "warning": self.warning,
+        }
+
+
+# t-distribution critical values (two-tailed, 95% confidence)
+_T_VALUES = {
+    1: 12.706, 2: 4.303, 3: 3.182, 4: 2.776, 5: 2.571,
+    6: 2.447, 7: 2.365, 8: 2.306, 9: 2.262, 10: 2.228,
+    15: 2.131, 20: 2.086, 25: 2.060, 30: 2.042, 40: 2.021,
+    50: 2.009, 100: 1.984, 200: 1.972, float("inf"): 1.960,
+}
+
+
+def _t_value(df: int) -> float:
+    if df in _T_VALUES:
+        return _T_VALUES[df]
+    if df > 200:
+        return _T_VALUES[float("inf")]
+    # Find closest key
+    closest = min(_T_VALUES.keys(), key=lambda k: abs(k - df) if k != float("inf") else abs(200 - df))
+    return _T_VALUES[closest]
+
+
+class StatisticalStabilityGuard:
+    """Check if sample sizes are large enough for stable results."""
+
+    def __init__(self, target_margin: float = 0.02, confidence: float = 0.95) -> None:
+        self.target_margin = target_margin
+        self.confidence = confidence
+
+    def evaluate(self, values: list[float]) -> StabilityReport:
+        n = len(values)
+        if n == 0:
+            return StabilityReport(
+                sample_size=0, mean=0.0, std_dev=0.0, margin_of_error=float("inf"),
+                confidence_level=self.confidence, is_stable=False,
+                recommended_sample_size=1, warning="No samples",
+            )
+        mean = sum(values) / n
+        if n == 1:
+            return StabilityReport(
+                sample_size=1, mean=mean, std_dev=0.0, margin_of_error=float("inf"),
+                confidence_level=self.confidence, is_stable=False,
+                recommended_sample_size=30, warning="Single sample — cannot estimate variance",
+            )
+        variance = sum((v - mean) ** 2 for v in values) / (n - 1)
+        std_dev = math.sqrt(variance)
+        t = _t_value(n - 1)
+        margin = t * std_dev / math.sqrt(n)
+        # Recommended sample size for target margin
+        if std_dev > 0 and margin > 0:
+            recommended = int(math.ceil((t * std_dev / self.target_margin) ** 2))
+        else:
+            recommended = n
+        is_stable = margin <= self.target_margin
+        warning = ""
+        if not is_stable:
+            warning = (
+                f"Margin of error {margin:.4f} exceeds target {self.target_margin:.4f}. "
+                f"Need ~{recommended} samples (have {n})."
+            )
+        return StabilityReport(
+            sample_size=n,
+            mean=mean,
+            std_dev=std_dev,
+            margin_of_error=margin,
+            confidence_level=self.confidence,
+            is_stable=is_stable,
+            recommended_sample_size=max(recommended, n),
+            warning=warning,
+        )