krnl-code 1.0.4__py3-none-any.whl

krnl_agent/__init__.py

@@ -0,0 +1,9 @@
+"""Krnl Agent — a lightweight, provider-agnostic agentic coding backend.
+
+Public surface:
+    from krnl_agent.config import load_config
+    from krnl_agent.llm import build_client
+    from krnl_agent.loop import AgentSession
+"""
+
+__version__ = "1.4.0"

krnl_agent/__main__.py

@@ -0,0 +1,7 @@
+"""Enable `python -m krnl_agent ...` (used by the VS Code auto-start)."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

krnl_agent/agent_registry.py

@@ -0,0 +1,95 @@
+"""Agent Registry for Phase 4: Agent Specialization.
+
+Defines specialized agents for different tasks (frontend, backend, testing, docs)
+with routing criteria based on keywords and file patterns.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class AgentDefinition:
+    """Definition of a specialized agent."""
+    name: str
+    keywords: list[str] = field(default_factory=list)
+    file_patterns: list[str] = field(default_factory=list)
+    description: str = ""
+
+
+# Default agent registry
+DEFAULT_AGENTS = [
+    AgentDefinition(
+        name="frontend",
+        keywords=["css", "html", "react", "vue", "frontend", "ui", "component"],
+        file_patterns=["*.css", "*.html", "*.jsx", "*.tsx", "*.vue"],
+        description="Specializes in frontend development, UI components, and styling.",
+    ),
+    AgentDefinition(
+        name="backend",
+        keywords=["api", "server", "backend", "endpoint", "service"],
+        file_patterns=["*.py", "*.js", "*.go", "*.rs", "*.java"],
+        description="Specializes in backend development, APIs, and server-side logic.",
+    ),
+    AgentDefinition(
+        name="testing",
+        keywords=["test", "spec", "pytest", "jest", "unit", "integration"],
+        file_patterns=["*test*.py", "test_*.py", "*.spec.js", "*.test.js"],
+        description="Specializes in writing and debugging tests.",
+    ),
+    AgentDefinition(
+        name="docs",
+        keywords=["doc", "readme", "markdown", "documentation"],
+        file_patterns=["*.md", "*.rst", "*.txt"],
+        description="Specializes in documentation and README files.",
+    ),
+    AgentDefinition(
+        name="database",
+        keywords=["sql", "schema", "migrate", "postgres", "db", "table", "query", "database"],
+        file_patterns=["*.sql", "*migrate*.py", "*schema*.py"],
+        description="Specializes in database schema design, migrations, and query performance.",
+    ),
+    AgentDefinition(
+        name="devops",
+        keywords=["docker", "kubernetes", "k8s", "ci", "cd", "workflow", "actions", "deployment", "terraform"],
+        file_patterns=["Dockerfile", "docker-compose.yml", "*.yaml", "*.yml", "*.tf"],
+        description="Specializes in CI/CD pipelines, containerization, deployment, and infrastructure.",
+    ),
+    AgentDefinition(
+        name="security",
+        keywords=["security", "auth", "login", "encrypt", "decrypt", "scan", "audit", "secrets"],
+        file_patterns=["*auth*.py", "*security*.py", "jwt*.py"],
+        description="Specializes in secure authentication, authorization, vulnerability scanning, and credentials handling.",
+    ),
+]
+
+
+class AgentRegistry:
+    """Registry of specialized agents."""
+
+    def __init__(self, agents: Optional[list[AgentDefinition]] = None):
+        self.agents = agents or [AgentDefinition(**a.__dict__) for a in DEFAULT_AGENTS]
+
+    def get_agent(self, name: str) -> Optional[AgentDefinition]:
+        """Get an agent definition by name."""
+        for agent in self.agents:
+            if agent.name == name:
+                return agent
+        return None
+
+    def list_agents(self) -> list[AgentDefinition]:
+        """List all registered agents."""
+        return self.agents.copy()
+
+    def add_agent(self, agent: AgentDefinition) -> None:
+        """Add a new agent to the registry."""
+        self.agents.append(agent)
+
+    def remove_agent(self, name: str) -> bool:
+        """Remove an agent from the registry. Returns True if removed."""
+        for i, agent in enumerate(self.agents):
+            if agent.name == name:
+                self.agents.pop(i)
+                return True
+        return False

krnl_agent/agent_selector.py

@@ -0,0 +1,69 @@
+"""Agent Selector for Phase 4: Agent Specialization.
+
+Routes tasks to specialized agents based on keywords and file patterns.
+"""
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+from typing import Optional
+
+from .agent_registry import AgentDefinition, AgentRegistry
+
+
+class AgentSelector:
+    """Selects the appropriate specialized agent for a task."""
+
+    def __init__(self, registry: Optional[AgentRegistry] = None):
+        self.registry = registry or AgentRegistry()
+
+    def select_agent(
+        self,
+        task: str,
+        file_paths: Optional[list[str]] = None,
+    ) -> Optional[AgentDefinition]:
+        """Select the best agent for a task based on keywords and file patterns.
+
+        Args:
+            task: The task description.
+            file_paths: List of file paths involved in the task.
+
+        Returns:
+            The selected agent definition, or None if no agent matches.
+        """
+        scores = {}
+
+        for agent in self.registry.list_agents():
+            score = 0
+
+            # Score based on task keywords
+            task_lower = task.lower()
+            for keyword in agent.keywords:
+                if keyword.lower() in task_lower:
+                    score += 1
+
+            # Score based on file patterns (with specificity bonus)
+            if file_paths:
+                for file_path in file_paths:
+                    file_name = Path(file_path).name
+                    for pattern in agent.file_patterns:
+                        if fnmatch.fnmatch(file_name, pattern):
+                            # Give higher score to more specific patterns
+                            # (patterns with more characters before/after wildcards)
+                            specificity = len(pattern.replace("*", ""))
+                            score += 1 + (specificity / 100)
+                            break
+
+            if score > 0:
+                scores[agent.name] = (score, agent)
+
+        if not scores:
+            return None
+
+        # Return the agent with the highest score
+        _, best_agent = max(scores.values(), key=lambda x: x[0])
+        return best_agent
+
+    def select_agent_by_name(self, name: str) -> Optional[AgentDefinition]:
+        """Select an agent by name (explicit selection)."""
+        return self.registry.get_agent(name)

krnl_agent/audit_log.py

@@ -0,0 +1,155 @@
+"""Tamper-evident, append-only audit log of agent actions.
+
+Every tool call (and its approval decision + outcome) is appended as one JSON line
+to `.krnl/audit/audit.log`. Each record carries a SHA-256 hash chained over the
+previous record's hash, so any insertion, deletion, or edit anywhere in the
+history breaks the chain and is detectable with `verify()`.
+
+This gives autonomous / dangerous-mode runs a reviewable, non-repudiable trail for
+compliance and debugging - "what did the agent actually do, in what order".
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+_GENESIS = "0" * 64
+
+
+def _rel_dir(workspace: str) -> Path:
+    return Path(workspace) / ".krnl" / "audit"
+
+
+def _log_path(workspace: str) -> Path:
+    return _rel_dir(workspace) / "audit.log"
+
+
+def _hash_record(prev_hash: str, payload: dict) -> str:
+    body = json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256((prev_hash + body).encode("utf-8")).hexdigest()
+
+
+def _last_hash(path: Path) -> str:
+    if not path.exists():
+        return _GENESIS
+    last = _GENESIS
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if line:
+                    try:
+                        last = json.loads(line).get("hash", last)
+                    except Exception:
+                        continue
+    except Exception:
+        return _GENESIS
+    return last
+
+
+class AuditLog:
+    """Append-only, hash-chained log. Construct once per session; cheap to call."""
+
+    def __init__(self, workspace: str, enabled: bool = True, *, seq_start: int | None = None):
+        self.workspace = workspace
+        self.enabled = enabled
+        self.path = _log_path(workspace)
+        self._prev = _last_hash(self.path) if enabled else _GENESIS
+        self._seq = seq_start if seq_start is not None else self._count()
+
+    def _count(self) -> int:
+        if not self.path.exists():
+            return 0
+        try:
+            with open(self.path, encoding="utf-8") as fh:
+                return sum(1 for ln in fh if ln.strip())
+        except Exception:
+            return 0
+
+    def record(self, *, ts: str, tool: str, args: dict, decision: str,
+               ok: bool | None = None, summary: str = "", depth: int = 0) -> None:
+        """Append one action. `ts` is supplied by the caller (no hidden clock)."""
+        if not self.enabled:
+            return
+        payload = {
+            "seq": self._seq,
+            "ts": ts,
+            "tool": tool,
+            "args": _shrink(args),
+            "decision": decision,
+            "ok": ok,
+            "summary": summary[:300],
+            "depth": depth,
+            "prev": self._prev,
+        }
+        h = _hash_record(self._prev, payload)
+        payload["hash"] = h
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.path, "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(payload, ensure_ascii=False) + "\n")
+            self._prev = h
+            self._seq += 1
+        except Exception:
+            pass  # auditing must never break the run
+
+
+def _shrink(args: dict) -> dict:
+    """Keep the log small and secret-light: truncate long string values."""
+    out = {}
+    for k, v in (args or {}).items():
+        if isinstance(v, str) and len(v) > 200:
+            out[k] = v[:200] + f"…(+{len(v) - 200})"
+        elif isinstance(v, (list, dict)) and len(json.dumps(v, default=str)) > 200:
+            out[k] = f"<{type(v).__name__} len {len(v)}>"
+        else:
+            out[k] = v
+    return out
+
+
+def verify(workspace: str) -> tuple[bool, str]:
+    """Re-walk the chain. Returns (intact, message)."""
+    path = _log_path(workspace)
+    if not path.exists():
+        return True, "No audit log yet."
+    prev = _GENESIS
+    n = 0
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for lineno, line in enumerate(fh, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                rec = json.loads(line)
+                stored = rec.pop("hash", None)
+                if rec.get("prev") != prev:
+                    return False, f"Chain break at line {lineno}: prev mismatch."
+                recomputed = _hash_record(prev, rec)
+                if recomputed != stored:
+                    return False, f"Tampering at line {lineno}: hash mismatch."
+                prev = stored
+                n += 1
+    except Exception as e:  # noqa: BLE001
+        return False, f"Audit log unreadable: {e}"
+    return True, f"Audit log intact — {n} record(s), chain verified."
+
+
+def tail(workspace: str, n: int = 20) -> str:
+    path = _log_path(workspace)
+    if not path.exists():
+        return "No audit log yet."
+    try:
+        lines = [ln for ln in path.read_text(encoding="utf-8").splitlines() if ln.strip()]
+    except Exception as e:  # noqa: BLE001
+        return f"Could not read audit log: {e}"
+    rows = []
+    for ln in lines[-n:]:
+        try:
+            r = json.loads(ln)
+            ok = "" if r.get("ok") is None else ("ok" if r["ok"] else "FAIL")
+            rows.append(f"{r.get('seq'):>4} {r.get('ts','')[:19]} {r.get('decision','?'):>5} "
+                        f"{r.get('tool',''):<16} {ok:<4} {r.get('summary','')}")
+        except Exception:
+            continue
+    return "\n".join(rows) if rows else "No records."

krnl_agent/background.py

@@ -0,0 +1,94 @@
+"""Background process manager for long-running commands (dev servers, watchers).
+
+`bash_background` starts a process and returns immediately with an id; its output
+is buffered by a reader thread and can be polled with `process_output`, listed
+with `process_list`, and stopped with `process_kill`.
+"""
+from __future__ import annotations
+
+import subprocess
+import threading
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BgProc:
+    id: str
+    command: str
+    proc: subprocess.Popen
+    lines: list = field(default_factory=list)
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+class BackgroundManager:
+    def __init__(self) -> None:
+        self._procs: dict[str, BgProc] = {}
+        self._counter = 0
+
+    def start(self, cwd: str, command: str) -> str:
+        self._counter += 1
+        pid = f"bg{self._counter}"
+        proc = subprocess.Popen(
+            command,
+            cwd=cwd,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+        bg = BgProc(pid, command, proc)
+        self._procs[pid] = bg
+
+        def reader():
+            try:
+                if proc.stdout:
+                    for line in proc.stdout:
+                        with bg.lock:
+                            bg.lines.append(line)
+                            if len(bg.lines) > 2000:
+                                del bg.lines[:1000]
+            except Exception:
+                pass
+
+        threading.Thread(target=reader, daemon=True).start()
+        return pid
+
+    def output(self, pid: str, tail: int = 100) -> str:
+        bg = self._procs.get(pid)
+        if not bg:
+            return f"no such process: {pid}"
+        with bg.lock:
+            text = "".join(bg.lines[-tail:])
+        status = "running" if bg.proc.poll() is None else f"exited ({bg.proc.returncode})"
+        return f"[{pid}] {status}\n{text}" if text else f"[{pid}] {status} (no output yet)"
+
+    def kill(self, pid: str) -> str:
+        bg = self._procs.get(pid)
+        if not bg:
+            return f"no such process: {pid}"
+        try:
+            bg.proc.kill()
+        except Exception:
+            pass
+        return f"killed {pid}"
+
+    def list_(self) -> str:
+        if not self._procs:
+            return "(no background processes)"
+        rows = []
+        for pid, bg in self._procs.items():
+            status = "running" if bg.proc.poll() is None else f"exited({bg.proc.returncode})"
+            rows.append(f"{pid}  {status}  {bg.command}")
+        return "\n".join(rows)
+
+    def kill_all(self) -> None:
+        for bg in self._procs.values():
+            try:
+                bg.proc.kill()
+            except Exception:
+                pass
+
+
+# One manager per process is fine; ids are unique within it.
+manager = BackgroundManager()

krnl_agent/checkpoints.py

@@ -0,0 +1,67 @@
+"""Checkpoint / undo for file mutations.
+
+Before any mutating file tool runs, the loop records the affected file's prior
+state here. `undo_last_turn()` restores everything changed during the most recent
+user turn — the "git checkpoint/revert" capability, without requiring git.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class FileSnapshot:
+    path: Path
+    existed: bool
+    content: str  # empty when the file didn't exist
+
+
+class Checkpointer:
+    def __init__(self) -> None:
+        # one list of snapshots per user turn (a stack of turns)
+        self._turns: list[list[FileSnapshot]] = []
+
+    def begin_turn(self) -> None:
+        self._turns.append([])
+
+    def record(self, full_path: Path) -> None:
+        """Snapshot a file's current state before it is mutated."""
+        if not self._turns:
+            self.begin_turn()
+        # avoid duplicate snapshots of the same path within a turn
+        for snap in self._turns[-1]:
+            if snap.path == full_path:
+                return
+        if full_path.exists():
+            try:
+                content = full_path.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                content = ""
+            self._turns[-1].append(FileSnapshot(full_path, True, content))
+        else:
+            self._turns[-1].append(FileSnapshot(full_path, False, ""))
+
+    @property
+    def can_undo(self) -> bool:
+        return any(turn for turn in self._turns)
+
+    def undo_last_turn(self) -> list[str]:
+        """Revert the most recent non-empty turn. Returns reverted paths."""
+        while self._turns:
+            turn = self._turns.pop()
+            if not turn:
+                continue
+            reverted: list[str] = []
+            for snap in reversed(turn):
+                try:
+                    if snap.existed:
+                        snap.path.parent.mkdir(parents=True, exist_ok=True)
+                        snap.path.write_text(snap.content, encoding="utf-8")
+                    elif snap.path.exists():
+                        snap.path.unlink()
+                    reverted.append(str(snap.path))
+                except Exception:
+                    continue
+            return reverted
+        return []

krnl_agent/ci.py

@@ -0,0 +1,73 @@
+"""CI recipe scaffolding.
+
+Generates a ready-to-use GitHub Actions workflow that runs the agent headlessly
+(`krnl-agent run --json`) to review pull requests and/or run the project's tests
+and a security pass. Written to `.github/workflows/krnl-agent.yml`.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+WORKFLOW = """\
+name: Krnl Agent
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Krnl Agent
+        run: pip install krnl-coding-agent
+
+      - name: Security + dependency scan
+        env:
+          # Set the key for your provider in repo Settings → Secrets.
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          krnl-agent run --json --yes \\
+            "Run secret_scan and dependency_audit on this repo. Summarize any \\
+             findings with severity and a concrete fix. Fail loudly if criticals."
+
+      - name: Review the diff
+        if: github.event_name == 'pull_request'
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          krnl-agent run --json --yes \\
+            "Review the changes on this branch vs the base for bugs, security \\
+             issues, and missing tests. Output a concise PR review."
+"""
+
+README_SNIPPET = """\
+## CI: Krnl Agent
+
+A GitHub Actions workflow at `.github/workflows/krnl-agent.yml` runs the agent on
+every pull request to scan for secrets/vulnerable deps and to review the diff.
+
+1. Add your provider key as a repo secret (e.g. `OPENAI_API_KEY`).
+2. Adjust the provider/model with `--provider`/`--model` if needed.
+"""
+
+
+def write_workflow(workspace: str, force: bool = False) -> tuple[bool, str]:
+    """Create the workflow file. Returns (written, path-or-message)."""
+    dest = Path(workspace) / ".github" / "workflows" / "krnl-agent.yml"
+    if dest.exists() and not force:
+        return False, f"{dest} already exists (use force to overwrite)."
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(WORKFLOW, encoding="utf-8")
+    except Exception as e:  # noqa: BLE001
+        return False, f"Could not write workflow: {e}"
+    return True, str(dest)