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

algo_cli/intelligence/rate_limiter.py

@@ -0,0 +1,153 @@
+"""Token Bucket Rate Limiter — smooth traffic shaping.
+
+A token bucket fills at a fixed rate (tokens per second) up to a maximum
+capacity (burst size).  Each request consumes one or more tokens.  If
+insufficient tokens are available, the request is denied (or delayed).
+
+Harness use:
+  - Throttle Ollama API calls to avoid rate limits
+  - Throttle embedding batches
+  - Throttle web fetches
+  - Throttle harness indexing rate
+
+The leaky bucket variant (output rate constant) is also provided.
+
+Operations:
+  - try_acquire(tokens=1): non-blocking, returns True/False
+  - acquire(tokens=1): blocking, sleeps until tokens available
+  - wait_time(tokens=1): returns seconds to wait
+
+Properties:
+  - Allows bursts up to capacity
+  - Long-term rate is capped at refill_rate
+  - O(1) per operation
+"""
+from __future__ import annotations
+
+import time
+from collections import deque
+from typing import Any
+
+
+class TokenBucket:
+    """Token bucket rate limiter.
+
+    Args:
+        capacity: Maximum tokens the bucket can hold (burst size).
+        refill_rate: Tokens added per second (sustained rate).
+    """
+
+    def __init__(self, capacity: float, refill_rate: float) -> None:
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if refill_rate <= 0:
+            raise ValueError("refill_rate must be positive")
+        self.capacity = float(capacity)
+        self.refill_rate = float(refill_rate)
+        self._tokens = float(capacity)  # start full
+        self._last_refill = time.monotonic()
+
+    def _refill(self) -> None:
+        """Add tokens based on elapsed time since last refill."""
+        now = time.monotonic()
+        elapsed = now - self._last_refill
+        self._tokens = min(self.capacity, self._tokens + elapsed * self.refill_rate)
+        self._last_refill = now
+
+    def try_acquire(self, tokens: float = 1.0) -> bool:
+        """Non-blocking attempt to acquire tokens.
+
+        Returns True if tokens were acquired, False if insufficient.
+        """
+        self._refill()
+        if self._tokens >= tokens:
+            self._tokens -= tokens
+            return True
+        return False
+
+    def wait_time(self, tokens: float = 1.0) -> float:
+        """Return seconds to wait until tokens are available."""
+        self._refill()
+        if self._tokens >= tokens:
+            return 0.0
+        needed = tokens - self._tokens
+        return needed / self.refill_rate
+
+    def acquire(self, tokens: float = 1.0, timeout: float | None = None) -> bool:
+        """Blocking acquire — sleeps until tokens are available.
+
+        Args:
+            tokens: Number of tokens to acquire.
+            timeout: Maximum seconds to wait. None = wait forever.
+
+        Returns:
+            True if acquired, False if timed out.
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            wait = self.wait_time(tokens)
+            if wait == 0.0:
+                self._refill()
+                self._tokens -= tokens
+                return True
+            if deadline is not None and time.monotonic() + wait > deadline:
+                return False
+            time.sleep(wait)
+
+    @property
+    def available_tokens(self) -> float:
+        """Current token count (after refilling)."""
+        self._refill()
+        return self._tokens
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "capacity": self.capacity,
+            "refill_rate": self.refill_rate,
+            "available_tokens": round(self.available_tokens, 2),
+        }
+
+
+class SlidingWindowCounter:
+    """Sliding window rate limiter — counts requests in a time window.
+
+    Uses a deque of timestamps, pruning entries older than the window.
+    Simple and accurate for small windows.
+
+    Args:
+        window_seconds: Size of the sliding window.
+        max_requests: Maximum requests allowed in the window.
+    """
+
+    def __init__(self, window_seconds: float, max_requests: int) -> None:
+        self.window_seconds = window_seconds
+        self.max_requests = max_requests
+        self._timestamps: deque[float] = deque()
+
+    def _prune(self, now: float) -> None:
+        """Remove timestamps outside the window."""
+        cutoff = now - self.window_seconds
+        while self._timestamps and self._timestamps[0] <= cutoff:
+            self._timestamps.popleft()
+
+    def try_acquire(self) -> bool:
+        """Non-blocking attempt to make a request."""
+        now = time.monotonic()
+        self._prune(now)
+        if len(self._timestamps) < self.max_requests:
+            self._timestamps.append(now)
+            return True
+        return False
+
+    def current_count(self) -> int:
+        """Number of requests in the current window."""
+        self._prune(time.monotonic())
+        return len(self._timestamps)
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "window_seconds": self.window_seconds,
+            "max_requests": self.max_requests,
+            "current_count": self.current_count(),
+            "remaining": max(0, self.max_requests - self.current_count()),
+        }

algo_cli/intelligence/refactor_transaction.py

@@ -0,0 +1,94 @@
+"""B83. Refactor Transaction with Savepoint/Rollback.
+
+Atomic refactoring with savepoints and rollback.
+Source: CCASP pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+
+
+class TransactionStatus(Enum):
+    ACTIVE = auto()
+    COMMITTED = auto()
+    ROLLED_BACK = auto()
+
+
+@dataclass
+class Savepoint:
+    name: str
+    file_snapshots: dict[str, str] = field(default_factory=dict)  # path → content
+
+
+@dataclass
+class TransactionResult:
+    status: TransactionStatus
+    savepoints: list[str] = field(default_factory=list)
+    files_modified: list[str] = field(default_factory=list)
+    error: str = ""
+
+
+class RefactorTransaction:
+    """Atomic refactoring with savepoint/rollback for multi-file changes."""
+
+    def __init__(self, workspace: Path) -> None:
+        self._workspace = workspace
+        self._savepoints: list[Savepoint] = []
+        self._modified: set[str] = set()
+        self._status: TransactionStatus = TransactionStatus.ACTIVE
+
+    def savepoint(self, name: str, files: list[str]) -> Savepoint:
+        """Create a savepoint with snapshots of the given files."""
+        if self._status != TransactionStatus.ACTIVE:
+            raise RuntimeError("Transaction not active")
+
+        sp = Savepoint(name=name)
+        for filepath in files:
+            try:
+                content = Path(filepath).read_text(encoding="utf-8")
+                sp.file_snapshots[filepath] = content
+            except FileNotFoundError:
+                sp.file_snapshots[filepath] = ""
+        self._savepoints.append(sp)
+        return sp
+
+    def rollback_to(self, savepoint_name: str) -> None:
+        """Rollback to a named savepoint."""
+        sp = next((s for s in self._savepoints if s.name == savepoint_name), None)
+        if not sp:
+            raise KeyError(f"Savepoint '{savepoint_name}' not found")
+
+        for filepath, content in sp.file_snapshots.items():
+            Path(filepath).write_text(content, encoding="utf-8")
+
+        # Remove savepoints after this one
+        idx = self._savepoints.index(sp)
+        self._savepoints = self._savepoints[:idx + 1]
+
+    def rollback_all(self) -> None:
+        """Rollback to the first savepoint (undo everything)."""
+        if self._savepoints:
+            self.rollback_to(self._savepoints[0].name)
+        self._status = TransactionStatus.ROLLED_BACK
+
+    def commit(self) -> TransactionResult:
+        """Commit the transaction — changes are permanent."""
+        self._status = TransactionStatus.COMMITTED
+        return TransactionResult(
+            status=self._status,
+            savepoints=[sp.name for sp in self._savepoints],
+            files_modified=list(self._modified),
+        )
+
+    def record_modification(self, filepath: str) -> None:
+        self._modified.add(filepath)
+
+    @property
+    def status(self) -> TransactionStatus:
+        return self._status
+
+    @property
+    def savepoint_names(self) -> list[str]:
+        return [sp.name for sp in self._savepoints]

algo_cli/intelligence/research_workspace.py

@@ -0,0 +1,108 @@
+"""B68. Virtual File System for Research Artifacts.
+
+Branch, persist, rejoin research investigations.
+Source: Morgana pattern.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ResearchArtifact:
+    id: str
+    name: str
+    content: str
+    artifact_type: str = "text"  # text, outline, finding, source, draft
+    created_at: float = field(default_factory=time.time)
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ResearchBranch:
+    id: str
+    parent_id: str | None = None
+    name: str = ""
+    artifacts: dict[str, ResearchArtifact] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+    status: str = "active"  # active, merged, abandoned
+
+
+class ResearchWorkspace:
+    """Virtual file system for research artifacts with branching."""
+
+    def __init__(self) -> None:
+        self._branches: dict[str, ResearchBranch] = {}
+        self._counter = 0
+        # Create root branch
+        self.create_branch("main", name="Main Research")
+
+    def create_branch(self, branch_id: str, parent_id: str | None = None,
+                      name: str = "") -> ResearchBranch:
+        branch = ResearchBranch(id=branch_id, parent_id=parent_id, name=name)
+        self._branches[branch_id] = branch
+        return branch
+
+    def add_artifact(self, branch_id: str, artifact: ResearchArtifact) -> None:
+        branch = self._branches.get(branch_id)
+        if not branch:
+            raise KeyError(f"Branch {branch_id} not found")
+        branch.artifacts[artifact.id] = artifact
+
+    def get_artifact(self, branch_id: str, artifact_id: str) -> ResearchArtifact | None:
+        branch = self._branches.get(branch_id)
+        if not branch:
+            return None
+        if artifact_id in branch.artifacts:
+            return branch.artifacts[artifact_id]
+        # Walk parent chain
+        if branch.parent_id:
+            return self.get_artifact(branch.parent_id, artifact_id)
+        return None
+
+    def list_artifacts(self, branch_id: str, include_parent: bool = True) -> list[ResearchArtifact]:
+        branch = self._branches.get(branch_id)
+        if not branch:
+            return []
+        artifacts = list(branch.artifacts.values())
+        if include_parent and branch.parent_id:
+            artifacts.extend(self.list_artifacts(branch.parent_id, include_parent=True))
+        return artifacts
+
+    def merge(self, source_id: str, target_id: str) -> int:
+        """Merge artifacts from source branch into target. Returns count merged."""
+        source = self._branches.get(source_id)
+        target = self._branches.get(target_id)
+        if not source or not target:
+            return 0
+        count = 0
+        for aid, artifact in source.artifacts.items():
+            if aid not in target.artifacts:
+                target.artifacts[aid] = artifact
+                count += 1
+        source.status = "merged"
+        return count
+
+    def search(self, branch_id: str, query: str) -> list[ResearchArtifact]:
+        """Search artifacts by name, content, or tags."""
+        artifacts = self.list_artifacts(branch_id)
+        query_lower = query.lower()
+        return [
+            a for a in artifacts
+            if query_lower in a.name.lower()
+            or query_lower in a.content.lower()
+            or any(query_lower in t.lower() for t in a.tags)
+        ]
+
+    def new_artifact_id(self) -> str:
+        self._counter += 1
+        return f"art_{self._counter}"
+
+    @property
+    def branch_count(self) -> int:
+        return len(self._branches)
+
+    @property
+    def artifact_count(self) -> int:
+        return sum(len(b.artifacts) for b in self._branches.values())

algo_cli/intelligence/retraction_ledger.py

@@ -0,0 +1,72 @@
+"""H3 — Retraction Ledger.
+
+Append-only retraction records, never silent deletes.
+Mined from T3MP3ST INTEGRITY_LEDGER.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RetractionEntry:
+    """A single retraction record."""
+
+    id: str
+    target_id: str
+    reason: str
+    retracted_at: float = field(default_factory=time.time)
+    retracted_by: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "target_id": self.target_id,
+            "reason": self.reason,
+            "retracted_at": self.retracted_at,
+            "retracted_by": self.retracted_by,
+            "metadata": dict(self.metadata),
+        }
+
+
+class RetractionLedger:
+    """Append-only ledger — entries can never be deleted, only added."""
+
+    def __init__(self) -> None:
+        self._entries: list[RetractionEntry] = []
+
+    def add(
+        self,
+        target_id: str,
+        reason: str,
+        retracted_by: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> RetractionEntry:
+        entry = RetractionEntry(
+            id=f"retraction-{len(self._entries) + 1:06d}",
+            target_id=target_id,
+            reason=reason,
+            retracted_by=retracted_by,
+            metadata=metadata or {},
+        )
+        self._entries.append(entry)
+        return entry
+
+    def is_retracted(self, target_id: str) -> bool:
+        return any(e.target_id == target_id for e in self._entries)
+
+    def get_retractions(self, target_id: str) -> list[RetractionEntry]:
+        return [e for e in self._entries if e.target_id == target_id]
+
+    def all(self) -> list[RetractionEntry]:
+        return list(self._entries)
+
+    def count(self) -> int:
+        return len(self._entries)
+
+    def delete(self, id: str) -> bool:
+        """Always returns False — retractions are permanent."""
+        return False

algo_cli/intelligence/saga_pattern.py

@@ -0,0 +1,88 @@
+"""B74. Saga Pattern for Multi-Agent Compensation.
+
+Each step defines a compensating action.  On failure, execute
+compensations in reverse order.
+Source: Claudient pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Callable, Any
+
+
+class SagaStepStatus(Enum):
+    PENDING = auto()
+    RUNNING = auto()
+    DONE = auto()
+    FAILED = auto()
+    COMPENSATED = auto()
+
+
+@dataclass
+class SagaStep:
+    name: str
+    execute: Callable[[], Any]
+    compensate: Callable[[], Any] | None = None
+    status: SagaStepStatus = SagaStepStatus.PENDING
+    result: Any = None
+    error: str | None = None
+
+
+@dataclass
+class SagaResult:
+    success: bool
+    completed_steps: list[str] = field(default_factory=list)
+    compensated_steps: list[str] = field(default_factory=list)
+    failed_step: str | None = None
+    error: str | None = None
+
+
+class SagaOrchestrator:
+    """Execute multi-step operations with automatic rollback."""
+
+    def __init__(self) -> None:
+        self._steps: list[SagaStep] = []
+
+    def add_step(self, step: SagaStep) -> None:
+        self._steps.append(step)
+
+    def execute(self) -> SagaResult:
+        """Execute all steps.  On failure, compensate in reverse."""
+        result = SagaResult(success=True)
+
+        for step in self._steps:
+            step.status = SagaStepStatus.RUNNING
+            try:
+                step.result = step.execute()
+                step.status = SagaStepStatus.DONE
+                result.completed_steps.append(step.name)
+            except Exception as e:
+                step.error = str(e)
+                step.status = SagaStepStatus.FAILED
+                result.success = False
+                result.failed_step = step.name
+                result.error = str(e)
+
+                # Compensate in reverse
+                self._compensate(result)
+                break
+
+        return result
+
+    def _compensate(self, result: SagaResult) -> None:
+        """Run compensations in reverse order."""
+        for step in reversed(self._steps):
+            if step.status != SagaStepStatus.DONE:
+                continue
+            if step.compensate:
+                try:
+                    step.compensate()
+                    step.status = SagaStepStatus.COMPENSATED
+                    result.compensated_steps.append(step.name)
+                except Exception:
+                    pass  # compensation failed — log but continue
+
+    @property
+    def steps(self) -> list[SagaStep]:
+        return list(self._steps)

algo_cli/intelligence/session_fork.py

@@ -0,0 +1,100 @@
+"""B52. Session Forking + Compaction Circuit Breaker.
+
+Fork sessions with parent pointers (no message duplication).
+Compaction circuit breaker prevents infinite compaction loops.
+Source: aloop pattern.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Message:
+    role: str  # "user", "assistant", "tool"
+    content: str
+    tool_call_id: str | None = None
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class SessionFork:
+    id: str
+    parent_id: str | None = None
+    messages: list[Message] = field(default_factory=list)
+    fork_point: int = 0  # index in parent's messages where fork occurred
+    depth: int = 0
+    created_at: float = field(default_factory=time.time)
+    materialized: bool = False
+
+    MAX_FORK_DEPTH = 10
+
+
+class SessionStore:
+    """Manage sessions with fork support and compaction circuit breaker."""
+
+    def __init__(self, max_compaction_failures: int = 3) -> None:
+        self._sessions: dict[str, SessionFork] = {}
+        self._compaction_failures: dict[str, int] = {}
+        self._max_compaction_failures = max_compaction_failures
+
+    def create(self, session_id: str, messages: list[Message] | None = None) -> SessionFork:
+        s = SessionFork(id=session_id, messages=list(messages or []))
+        self._sessions[session_id] = s
+        return s
+
+    def fork(
+        self,
+        parent_id: str,
+        fork_id: str,
+        fork_point: int | None = None,
+    ) -> SessionFork:
+        parent = self._sessions.get(parent_id)
+        if parent is None:
+            raise KeyError(f"Parent session {parent_id} not found")
+        if parent.depth >= SessionFork.MAX_FORK_DEPTH:
+            raise ValueError(f"Max fork depth ({SessionFork.MAX_FORK_DEPTH}) exceeded")
+
+        fp = fork_point if fork_point is not None else len(parent.messages)
+        child = SessionFork(
+            id=fork_id,
+            parent_id=parent_id,
+            fork_point=fp,
+            depth=parent.depth + 1,
+        )
+        # Child does NOT copy messages — uses parent pointer
+        self._sessions[fork_id] = child
+        return child
+
+    def get_messages(self, session_id: str) -> list[Message]:
+        """Resolve messages by walking parent chain."""
+        s = self._sessions.get(session_id)
+        if s is None:
+            return []
+        if s.parent_id is None:
+            return list(s.messages)
+        parent_msgs = self.get_messages(s.parent_id)[: s.fork_point]
+        return parent_msgs + list(s.messages)
+
+    def materialize(self, session_id: str) -> list[Message]:
+        """Flatten fork chain into a single message list."""
+        msgs = self.get_messages(session_id)
+        s = self._sessions[session_id]
+        s.materialized = True
+        s.messages = list(msgs)
+        s.parent_id = None
+        return msgs
+
+    def can_compact(self, session_id: str) -> bool:
+        """Circuit breaker: prevent compaction if too many failures."""
+        return self._compaction_failures.get(session_id, 0) < self._max_compaction_failures
+
+    def record_compaction_failure(self, session_id: str) -> None:
+        self._compaction_failures[session_id] = self._compaction_failures.get(session_id, 0) + 1
+
+    def reset_compaction(self, session_id: str) -> None:
+        self._compaction_failures.pop(session_id, None)
+
+    def list_forks(self, parent_id: str) -> list[str]:
+        return [sid for sid, s in self._sessions.items() if s.parent_id == parent_id]

algo_cli/intelligence/shadow_editor.py

@@ -0,0 +1,67 @@
+"""B79. Shadow Editor: LSP Diff Validation.
+
+Diff LSP diagnostics before and after each edit to catch introduced errors.
+Source: Pathfinder pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class LSPDiagnostic:
+    severity: str
+    message: str
+    line: int
+    col: int
+    source: str = ""
+
+
+@dataclass
+class EditValidation:
+    safe: bool
+    introduced: list[LSPDiagnostic] = field(default_factory=list)
+    resolved: list[LSPDiagnostic] = field(default_factory=list)
+    unchanged: list[LSPDiagnostic] = field(default_factory=list)
+
+
+class ShadowEditor:
+    """Validate edits against LSP before writing to disk."""
+
+    def __init__(self, get_diagnostics_fn: Callable[[str, str], list[LSPDiagnostic]] | None = None) -> None:
+        self._get_diagnostics = get_diagnostics_fn or self._noop_diagnostics
+
+    @staticmethod
+    def _noop_diagnostics(filepath: str, content: str) -> list[LSPDiagnostic]:
+        return []
+
+    def validate_edit(self, filepath: str, old_content: str, new_content: str) -> EditValidation:
+        """Validate an edit by comparing diagnostics before and after."""
+        before = self._get_diagnostics(filepath, old_content)
+        after = self._get_diagnostics(filepath, new_content)
+
+        introduced = self._diff_new(before, after)
+        resolved = self._diff_new(after, before)
+        unchanged = self._intersect(before, after)
+
+        return EditValidation(
+            safe=len([d for d in introduced if d.severity == "error"]) == 0,
+            introduced=introduced,
+            resolved=resolved,
+            unchanged=unchanged,
+        )
+
+    def _diff_new(self, before: list[LSPDiagnostic], after: list[LSPDiagnostic]) -> list[LSPDiagnostic]:
+        """Find diagnostics in 'after' that weren't in 'before'."""
+        before_keys = {(d.severity, d.message, d.line) for d in before}
+        return [d for d in after if (d.severity, d.message, d.line) not in before_keys]
+
+    def _intersect(self, before: list[LSPDiagnostic], after: list[LSPDiagnostic]) -> list[LSPDiagnostic]:
+        """Find diagnostics present in both."""
+        after_keys = {(d.severity, d.message, d.line) for d in after}
+        return [d for d in before if (d.severity, d.message, d.line) in after_keys]
+
+    def should_block(self, validation: EditValidation) -> bool:
+        """Should the edit be blocked?"""
+        return any(d.severity == "error" for d in validation.introduced)