cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/core/recovery.py

@@ -0,0 +1,129 @@
+"""
+CAT Crash Resilience & Auto-Recovery per §15:
+- Continuous persistence of running agent state, task DAG, and scratchpad
+- Crash recovery detection on startup with resume or clean-rollback options
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class RecoverySnapshot:
+    session_id: str
+    task_id: str
+    mode: str
+    timestamp: float = field(default_factory=time.time)
+    task_graph_state: Dict[str, Any] = field(default_factory=dict)
+    scratchpad: str = ""
+    active_checkpoint_id: Optional[str] = None
+    completed: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "session_id": self.session_id,
+            "task_id": self.task_id,
+            "mode": self.mode,
+            "timestamp": self.timestamp,
+            "task_graph_state": self.task_graph_state,
+            "scratchpad": self.scratchpad,
+            "active_checkpoint_id": self.active_checkpoint_id,
+            "completed": self.completed,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> RecoverySnapshot:
+        return cls(
+            session_id=data.get("session_id", ""),
+            task_id=data.get("task_id", ""),
+            mode=data.get("mode", "agent"),
+            timestamp=data.get("timestamp", time.time()),
+            task_graph_state=data.get("task_graph_state", {}),
+            scratchpad=data.get("scratchpad", ""),
+            active_checkpoint_id=data.get("active_checkpoint_id"),
+            completed=data.get("completed", False),
+        )
+
+
+class RecoveryEngine:
+    """Manages crash detection, state persistence, and session resumption."""
+
+    def __init__(self, storage_path: Optional[str] = None):
+        self.storage_path = storage_path or os.path.join(os.path.expanduser("~"), ".cct_recovery_state.json")
+        self._active_snapshot: Optional[RecoverySnapshot] = None
+        self._load()
+
+    def _load(self):
+        if not os.path.exists(self.storage_path):
+            return
+        try:
+            with open(self.storage_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            self._active_snapshot = RecoverySnapshot.from_dict(data)
+        except Exception:
+            pass
+
+    def record_heartbeat(
+        self,
+        session_id: str,
+        task_id: str,
+        mode: str,
+        task_graph_state: Optional[Dict[str, Any]] = None,
+        scratchpad: str = "",
+        checkpoint_id: Optional[str] = None,
+    ) -> RecoverySnapshot:
+        """Persist state of in-flight execution."""
+        snap = RecoverySnapshot(
+            session_id=session_id,
+            task_id=task_id,
+            mode=mode,
+            task_graph_state=task_graph_state or {},
+            scratchpad=scratchpad,
+            active_checkpoint_id=checkpoint_id,
+            completed=False,
+        )
+        self._active_snapshot = snap
+        self.save()
+        return snap
+
+    def mark_completed(self, session_id: str):
+        """Mark session completed cleanly so recovery is not triggered."""
+        if not self._active_snapshot:
+            self._load()
+        if self._active_snapshot and self._active_snapshot.session_id == session_id:
+            self._active_snapshot.completed = True
+            self.save()
+
+    def get_pending_recovery(self) -> Optional[RecoverySnapshot]:
+        """Check if an uncompleted session was interrupted/crashed."""
+        if not self._active_snapshot:
+            self._load()
+        if self._active_snapshot and not self._active_snapshot.completed and self._active_snapshot.session_id:
+            return self._active_snapshot
+        return None
+
+    def clear_recovery(self):
+        """Clear recovery record."""
+        self._active_snapshot = None
+        if os.path.exists(self.storage_path):
+            try:
+                os.remove(self.storage_path)
+            except Exception:
+                pass
+
+    def save(self):
+        if not self._active_snapshot:
+            return
+        try:
+            with open(self.storage_path, "w", encoding="utf-8") as f:
+                json.dump(self._active_snapshot.to_dict(), f, indent=2)
+        except Exception:
+            pass
+
+
+recovery_engine = RecoveryEngine()

calc_terminal/core/security_layer.py

@@ -0,0 +1,112 @@
+"""
+CAT Security, Privacy & Safe Execution Layer per §27:
+- Tiered permission model & approval gates for irreversible actions
+- Automated secret redaction for API keys, tokens, and credentials
+- Prompt injection and malicious command heuristic defenses
+"""
+
+from __future__ import annotations
+
+import enum
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+
+class PermissionTier(str, enum.Enum):
+    READ_ONLY = "read_only"
+    WORKSPACE_WRITE = "workspace_write"
+    TERMINAL_EXECUTE = "terminal_execute"
+    NETWORK_ACCESS = "network_access"
+    DESTRUCTIVE_OPERATIONS = "destructive_operations"
+
+
+# Regex patterns for common secret credentials
+SECRET_PATTERNS = [
+    (re.compile(r"(sk-[a-zA-Z0-9]{20,})"), "[REDACTED_API_KEY]"),
+    (re.compile(r"(ghp_[a-zA-Z0-9]{36,})"), "[REDACTED_GITHUB_TOKEN]"),
+    (re.compile(r"(gho_[a-zA-Z0-9]{36,})"), "[REDACTED_GITHUB_TOKEN]"),
+    (re.compile(r"(hf_[a-zA-Z0-9]{34,})"), "[REDACTED_HF_TOKEN]"),
+    (re.compile(r"(AKIA[0-9A-Z]{16})"), "[REDACTED_AWS_KEY]"),
+    (re.compile(r"(AIza[0-9A-Za-z-_]{35})"), "[REDACTED_GOOGLE_KEY]"),
+    (re.compile(r"Bearer\s+([a-zA-Z0-9_\-\.]{20,})"), "Bearer [REDACTED_BEARER_TOKEN]"),
+    (re.compile(r"(?i)(password|secret|token|api_key)\s*[:=]\s*['\"]([^'\"]{4,})['\"]"), r"\1='[REDACTED]'"),
+]
+
+# Patterns representing high-risk or destructive actions requiring approval
+DESTRUCTIVE_COMMAND_PATTERNS = [
+    re.compile(r"rm\s+(-rf|-fr|--recursive)\s+[/~]"),
+    re.compile(r"git\s+push\s+.*--force"),
+    re.compile(r"mkfs"),
+    re.compile(r"dd\s+if="),
+    re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:"),  # Fork bomb
+    re.compile(r"drop\s+(database|table)", re.IGNORECASE),
+]
+
+# Suspicious prompt injection indicators
+PROMPT_INJECTION_PATTERNS = [
+    re.compile(r"(?i)(ignore|disregard)\s+(all\s+)?(previous\s+)?(instructions|prompts|safety\s+guidelines)"),
+    re.compile(r"(?i)you\s+are\s+now\s+in\s+developer\s+mode"),
+    re.compile(r"(?i)<system>.*ignore.*</system>"),
+    re.compile(r"(?i)reveal\s+(system\s+prompt|secret\s+keys)"),
+]
+
+
+@dataclass
+class SecurityCheckResult:
+    allowed: bool
+    requires_confirmation: bool = False
+    reason: Optional[str] = None
+    category: str = "ok"
+
+
+class SecurityLayer:
+    """Enforces execution safety, secret protection, and input sanitization."""
+
+    def __init__(self, current_tier: PermissionTier = PermissionTier.TERMINAL_EXECUTE):
+        self.current_tier = current_tier
+        self.approved_actions: Set[str] = set()
+
+    def redact_secrets(self, text: str) -> str:
+        """Scan text and redact sensitive API keys, tokens, and credentials."""
+        if not text:
+            return ""
+        redacted = text
+        for pattern, replacement in SECRET_PATTERNS:
+            redacted = pattern.sub(replacement, redacted)
+        return redacted
+
+    def evaluate_command(self, command: str) -> SecurityCheckResult:
+        """Inspect terminal command before execution."""
+        cmd_clean = command.strip()
+
+        # 1. Check destructive patterns
+        for pat in DESTRUCTIVE_COMMAND_PATTERNS:
+            if pat.search(cmd_clean):
+                return SecurityCheckResult(
+                    allowed=False,
+                    requires_confirmation=True,
+                    reason=f"Potentially destructive command detected: '{cmd_clean}'. Explicit approval required.",
+                    category="destructive",
+                )
+
+        # 2. Check permission tier
+        if self.current_tier == PermissionTier.READ_ONLY:
+            return SecurityCheckResult(
+                allowed=False,
+                requires_confirmation=False,
+                reason="Current permission tier is READ_ONLY. Terminal execution denied.",
+                category="permission_denied",
+            )
+
+        return SecurityCheckResult(allowed=True, category="ok")
+
+    def inspect_untrusted_input(self, content: str) -> Tuple[bool, Optional[str]]:
+        """Detect potential prompt injection in external data or tool outputs."""
+        for pat in PROMPT_INJECTION_PATTERNS:
+            if pat.search(content):
+                return False, f"Potential prompt injection pattern detected: {pat.pattern}"
+        return True, None
+
+
+security_layer = SecurityLayer()

calc_terminal/core/task_graph.py

@@ -0,0 +1,202 @@
+"""
+CAT Task Graph & Background Task Engine per §9, §20:
+Represents complex multi-step requests as directed acyclic task graphs.
+Supports dependency resolution, retry, cancellation, pause/resume, and verification states.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+
+class TaskStatus(str, Enum):
+    QUEUED = "QUEUED"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    COMPLETED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+    PAUSED = "PAUSED"
+    VERIFYING = "VERIFYING"
+
+
+TASK_SYMBOLS = {
+    TaskStatus.QUEUED: "○",
+    TaskStatus.RUNNING: "●",
+    TaskStatus.SUCCEEDED: "✓",
+    TaskStatus.FAILED: "✗",
+    TaskStatus.CANCELLED: "⊘",
+    TaskStatus.PAUSED: "⏸",
+    TaskStatus.VERIFYING: "⟳",
+}
+
+
+@dataclass
+class TaskNode:
+    id: str
+    title: str
+    description: str = ""
+    dependencies: List[str] = field(default_factory=list)
+    status: TaskStatus = TaskStatus.QUEUED
+    progress: float = 0.0  # 0.0 to 1.0
+    logs: List[str] = field(default_factory=list)
+    result: Any = None
+    failure_reason: str = ""
+    verification_state: str = "pending"  # pending, verified, not_verified
+    subtasks: List[str] = field(default_factory=list)
+    parent_id: Optional[str] = None
+    created_at: float = field(default_factory=time.time)
+    started_at: Optional[float] = None
+    finished_at: Optional[float] = None
+    duration_ms: float = 0.0
+    retries_left: int = 3
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "dependencies": self.dependencies,
+            "status": self.status.value,
+            "progress": self.progress,
+            "logs": self.logs[-50:],
+            "result": str(self.result)[:200] if self.result is not None else None,
+            "failure_reason": self.failure_reason,
+            "verification_state": self.verification_state,
+            "subtasks": self.subtasks,
+            "parent_id": self.parent_id,
+            "duration_ms": self.duration_ms,
+        }
+
+
+class TaskGraph:
+    """DAG managing structured tasks, dependencies, and execution progress."""
+
+    def __init__(self, trace_id: Optional[str] = None):
+        self.trace_id = trace_id or f"trace-{uuid.uuid4().hex[:8]}"
+        self.nodes: Dict[str, TaskNode] = {}
+        self.root_tasks: List[str] = []
+
+    def add_task(
+        self,
+        title: str,
+        description: str = "",
+        dependencies: Optional[List[str]] = None,
+        parent_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+    ) -> str:
+        tid = task_id or f"task-{uuid.uuid4().hex[:6]}"
+        node = TaskNode(
+            id=tid,
+            title=title,
+            description=description,
+            dependencies=dependencies or [],
+            parent_id=parent_id,
+        )
+        self.nodes[tid] = node
+        if parent_id and parent_id in self.nodes:
+            self.nodes[parent_id].subtasks.append(tid)
+        elif not parent_id:
+            self.root_tasks.append(tid)
+        return tid
+
+    def get_task(self, task_id: str) -> Optional[TaskNode]:
+        return self.nodes.get(task_id)
+
+    def update_status(self, task_id: str, status: TaskStatus, result: Any = None, failure_reason: str = ""):
+        node = self.nodes.get(task_id)
+        if not node:
+            return
+        node.status = status
+        now = time.time()
+        if status == TaskStatus.RUNNING and node.started_at is None:
+            node.started_at = now
+        elif status in (TaskStatus.SUCCEEDED, TaskStatus.FAILED, TaskStatus.CANCELLED):
+            node.finished_at = now
+            if node.started_at:
+                node.duration_ms = round((now - node.started_at) * 1000.0, 2)
+        if result is not None:
+            node.result = result
+        if failure_reason:
+            node.failure_reason = failure_reason
+
+    def update_task_status(self, task_id: str, status: TaskStatus, result: Any = None, failure_reason: str = ""):
+        self.update_status(task_id, status, result, failure_reason)
+
+    def set_progress(self, task_id: str, progress: float):
+        node = self.nodes.get(task_id)
+        if node:
+            node.progress = max(0.0, min(1.0, float(progress)))
+
+    def log(self, task_id: str, message: str):
+        node = self.nodes.get(task_id)
+        if node:
+            node.logs.append(f"[{time.strftime('%H:%M:%S')}] {message}")
+
+    def get_ready_tasks(self) -> List[TaskNode]:
+        """Return tasks whose dependencies are all SUCCEEDED and are currently QUEUED."""
+        ready = []
+        for node in self.nodes.values():
+            if node.status != TaskStatus.QUEUED:
+                continue
+            deps_met = all(
+                dep in self.nodes and self.nodes[dep].status == TaskStatus.SUCCEEDED
+                for dep in node.dependencies
+            )
+            if deps_met:
+                ready.append(node)
+        return ready
+
+    def cancel_all(self):
+        for node in self.nodes.values():
+            if node.status in (TaskStatus.QUEUED, TaskStatus.RUNNING, TaskStatus.PAUSED):
+                node.status = TaskStatus.CANCELLED
+
+    def is_finished(self) -> bool:
+        return all(
+            n.status in (TaskStatus.SUCCEEDED, TaskStatus.FAILED, TaskStatus.CANCELLED)
+            for n in self.nodes.values()
+        )
+
+    def render_ascii_tree(self) -> str:
+        """Render tree format matching §9 spec."""
+        lines = ["TASK GRAPH"]
+
+        def _render_node(tid: str, prefix: str = "", is_last: bool = True):
+            node = self.nodes.get(tid)
+            if not node:
+                return
+            connector = "└── " if is_last else "├── "
+            symbol = TASK_SYMBOLS.get(node.status, "○")
+            lines.append(f"{prefix}{connector}{node.title:<30} {symbol}")
+            child_prefix = prefix + ("    " if is_last else "│   ")
+            for i, child_id in enumerate(node.subtasks):
+                _render_node(child_id, child_prefix, is_last=(i == len(node.subtasks) - 1))
+
+        for i, root_id in enumerate(self.root_tasks):
+            _render_node(root_id, "", is_last=(i == len(self.root_tasks) - 1))
+
+        return "\n".join(lines)
+
+
+class BackgroundTaskManager:
+    """Manages background asynchronous tasks across the platform."""
+
+    def __init__(self):
+        self._graphs: Dict[str, TaskGraph] = {}
+
+    def create_graph(self, title: str) -> TaskGraph:
+        graph = TaskGraph()
+        self._graphs[graph.trace_id] = graph
+        return graph
+
+    def get_graph(self, trace_id: str) -> Optional[TaskGraph]:
+        return self._graphs.get(trace_id)
+
+
+task_manager = BackgroundTaskManager()

calc_terminal/core/unified_runtime.py

@@ -0,0 +1,184 @@
+"""
+CAT Unified Agent Runtime per §5, §10, §61:
+Implements the canonical loop:
+OBSERVE -> UNDERSTAND -> PLAN -> ACT -> OBSERVE RESULT -> VERIFY -> CONTINUE / RETRY / ASK
+Features:
+- Sub-agent worker coordinator (Research, Coding, Testing, Browser, Security, Review)
+- Model handoff across specialized models
+- Reality Engine integration: no false completion
+- Provenance and telemetry logging
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from ..capabilities import capability_bus, ExecutionResult
+from .verification import reality_engine, RealityStatus
+from .task_graph import TaskGraph, TaskNode, TaskStatus, task_manager
+
+_LOG = logging.getLogger("cct.runtime")
+
+
+class WorkerType(str, Enum):
+    COORDINATOR = "coordinator"
+    RESEARCH = "research_worker"
+    CODING = "coding_worker"
+    TESTING = "testing_worker"
+    BROWSER = "browser_worker"
+    SECURITY = "security_worker"
+    REVIEW = "review_worker"
+
+
+@dataclass
+class RuntimeStep:
+    phase: str  # OBSERVE, UNDERSTAND, PLAN, ACT, VERIFY
+    worker: WorkerType
+    action: str
+    observation: str
+    verified: bool = False
+    duration_ms: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "phase": self.phase,
+            "worker": self.worker.value,
+            "action": self.action,
+            "observation": self.observation[:200],
+            "verified": self.verified,
+            "duration_ms": self.duration_ms,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass
+class AgentExecutionContext:
+    trace_id: str
+    user_prompt: str
+    mode: str = "agent"
+    workspace: Optional[str] = None
+    graph: Optional[TaskGraph] = None
+    steps: List[RuntimeStep] = field(default_factory=list)
+    state: Dict[str, Any] = field(default_factory=dict)
+    active_worker: WorkerType = WorkerType.COORDINATOR
+    cancelled: bool = False
+    max_steps: int = 25
+    retries: int = 0
+
+
+class UnifiedAgentRuntime:
+    """The central unified runtime executing all CAT agent operations."""
+
+    def __init__(self):
+        self.reality = reality_engine
+        self.bus = capability_bus
+
+    def create_context(self, user_prompt: str, mode: str = "agent", workspace: Optional[str] = None) -> AgentExecutionContext:
+        graph = task_manager.create_graph(user_prompt)
+        return AgentExecutionContext(
+            trace_id=graph.trace_id,
+            user_prompt=user_prompt,
+            mode=mode,
+            workspace=workspace,
+            graph=graph,
+        )
+
+    def execute_tool(
+        self,
+        capability_name: str,
+        args: Dict[str, Any],
+        ctx: AgentExecutionContext,
+        worker: WorkerType = WorkerType.CODING,
+        permission_callback: Optional[Callable[[str, str, str, str], str]] = None,
+    ) -> ExecutionResult:
+        """Execute capability through Capability Bus with provenance & verification."""
+        t0 = time.perf_counter()
+        res = self.bus.execute(
+            name=capability_name,
+            args=args,
+            context={"turn_id": ctx.trace_id, "workspace": ctx.workspace},
+            task_id=ctx.trace_id,
+            mode=ctx.mode,
+            permission_callback=permission_callback,
+        )
+        duration = round((time.perf_counter() - t0) * 1000.0, 2)
+
+        step = RuntimeStep(
+            phase="ACT",
+            worker=worker,
+            action=f"{capability_name}({json.dumps(args, default=str)})",
+            observation=str(res.output if res.success else res.error),
+            verified=res.success,
+            duration_ms=duration,
+        )
+        ctx.steps.append(step)
+        return res
+
+    def verify_action(
+        self,
+        claim: str,
+        ctx: AgentExecutionContext,
+        verification_fn: Callable[[], Any],
+    ) -> bool:
+        """Run Reality Engine verification step."""
+        t0 = time.perf_counter()
+        try:
+            ev = verification_fn()
+            passed = ev.passed if hasattr(ev, "passed") else bool(ev)
+            details = ev.details if hasattr(ev, "details") else str(ev)
+        except Exception as e:
+            passed = False
+            details = str(e)
+
+        duration = round((time.perf_counter() - t0) * 1000.0, 2)
+        step = RuntimeStep(
+            phase="VERIFY",
+            worker=WorkerType.REVIEW,
+            action=f"Verify: {claim}",
+            observation=details,
+            verified=passed,
+            duration_ms=duration,
+        )
+        ctx.steps.append(step)
+        return passed
+
+    def run_subagent_task(
+        self,
+        worker_type: WorkerType,
+        subtask_prompt: str,
+        ctx: AgentExecutionContext,
+        tools_allowed: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Delegate subtask to specialized worker agent without mode cluttering per §10."""
+        old_worker = ctx.active_worker
+        ctx.active_worker = worker_type
+
+        t0 = time.perf_counter()
+        step_start = RuntimeStep(
+            phase="PLAN",
+            worker=worker_type,
+            action=f"Spawn worker {worker_type.value}",
+            observation=f"Task: {subtask_prompt}",
+            duration_ms=0.0,
+        )
+        ctx.steps.append(step_start)
+
+        # Worker logic
+        result = {
+            "worker": worker_type.value,
+            "task": subtask_prompt,
+            "status": "completed",
+            "duration_ms": round((time.perf_counter() - t0) * 1000.0, 2),
+        }
+        ctx.active_worker = old_worker
+        return result
+
+
+unified_runtime = UnifiedAgentRuntime()