corecoder 0.2.0__py3-none-any.whl

corecoder/llm.py

@@ -0,0 +1,156 @@
+"""LLM provider layer - thin wrapper over OpenAI-compatible APIs.
+
+Since most providers (DeepSeek, Qwen, Kimi, GLM, Ollama, etc.) expose an
+OpenAI-compatible endpoint, we just use the openai SDK directly.  Switch
+provider by changing OPENAI_BASE_URL + OPENAI_API_KEY. That's it.
+"""
+
+import json
+import time
+from dataclasses import dataclass, field
+
+from openai import OpenAI, APIError, RateLimitError, APITimeoutError, APIConnectionError
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict
+
+
+@dataclass
+class LLMResponse:
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+    @property
+    def message(self) -> dict:
+        """Convert to OpenAI message format for appending to history."""
+        msg: dict = {"role": "assistant", "content": self.content or None}
+        if self.tool_calls:
+            msg["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {
+                        "name": tc.name,
+                        "arguments": json.dumps(tc.arguments),
+                    },
+                }
+                for tc in self.tool_calls
+            ]
+        return msg
+
+
+class LLM:
+    def __init__(
+        self,
+        model: str,
+        api_key: str,
+        base_url: str | None = None,
+        **kwargs,
+    ):
+        self.model = model
+        self.client = OpenAI(api_key=api_key, base_url=base_url)
+        self.extra = kwargs  # temperature, max_tokens, etc.
+        self.total_prompt_tokens = 0
+        self.total_completion_tokens = 0
+
+    def chat(
+        self,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        on_token=None,
+    ) -> LLMResponse:
+        """Send messages, stream back response, handle tool calls."""
+        params: dict = {
+            "model": self.model,
+            "messages": messages,
+            "stream": True,
+            **self.extra,
+        }
+        if tools:
+            params["tools"] = tools
+
+        # stream_options is an OpenAI extension; not all providers support it
+        try:
+            params["stream_options"] = {"include_usage": True}
+            stream = self._call_with_retry(params)
+        except Exception:
+            params.pop("stream_options", None)
+            stream = self._call_with_retry(params)
+
+        content_parts: list[str] = []
+        tc_map: dict[int, dict] = {}  # index -> {id, name, arguments_str}
+        prompt_tok = 0
+        completion_tok = 0
+
+        for chunk in stream:
+            # usage info comes in the final chunk
+            if chunk.usage:
+                prompt_tok = chunk.usage.prompt_tokens
+                completion_tok = chunk.usage.completion_tokens
+
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta
+
+            # accumulate text
+            if delta.content:
+                content_parts.append(delta.content)
+                if on_token:
+                    on_token(delta.content)
+
+            # accumulate tool calls across chunks
+            if delta.tool_calls:
+                for tc_delta in delta.tool_calls:
+                    idx = tc_delta.index
+                    if idx not in tc_map:
+                        tc_map[idx] = {"id": "", "name": "", "args": ""}
+                    if tc_delta.id:
+                        tc_map[idx]["id"] = tc_delta.id
+                    if tc_delta.function:
+                        if tc_delta.function.name:
+                            tc_map[idx]["name"] = tc_delta.function.name
+                        if tc_delta.function.arguments:
+                            tc_map[idx]["args"] += tc_delta.function.arguments
+
+        # parse accumulated tool calls
+        parsed: list[ToolCall] = []
+        for idx in sorted(tc_map):
+            raw = tc_map[idx]
+            try:
+                args = json.loads(raw["args"])
+            except (json.JSONDecodeError, KeyError):
+                args = {}
+            parsed.append(ToolCall(id=raw["id"], name=raw["name"], arguments=args))
+
+        self.total_prompt_tokens += prompt_tok
+        self.total_completion_tokens += completion_tok
+
+        return LLMResponse(
+            content="".join(content_parts),
+            tool_calls=parsed,
+            prompt_tokens=prompt_tok,
+            completion_tokens=completion_tok,
+        )
+
+    def _call_with_retry(self, params: dict, max_retries: int = 3):
+        """Retry on transient errors with exponential backoff."""
+        for attempt in range(max_retries):
+            try:
+                return self.client.chat.completions.create(**params)
+            except (RateLimitError, APITimeoutError, APIConnectionError) as e:
+                if attempt == max_retries - 1:
+                    raise
+                wait = 2 ** attempt
+                time.sleep(wait)
+            except APIError as e:
+                # 5xx = server error, retry; 4xx = client error, don't
+                if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
+                    time.sleep(2 ** attempt)
+                else:
+                    raise

corecoder/prompt.py

@@ -0,0 +1,33 @@
+"""System prompt - the instructions that turn an LLM into a coding agent."""
+
+import os
+import platform
+
+
+def system_prompt(tools) -> str:
+    cwd = os.getcwd()
+    tool_list = "\n".join(f"- **{t.name}**: {t.description}" for t in tools)
+    uname = platform.uname()
+
+    return f"""\
+You are CoreCoder, an AI coding assistant running in the user's terminal.
+You help with software engineering: writing code, fixing bugs, refactoring, explaining code, running commands, and more.
+
+# Environment
+- Working directory: {cwd}
+- OS: {uname.system} {uname.release} ({uname.machine})
+- Python: {platform.python_version()}
+
+# Tools
+{tool_list}
+
+# Rules
+1. **Read before edit.** Always read a file before modifying it.
+2. **edit_file for small changes.** Use edit_file for targeted edits; write_file only for new files or complete rewrites.
+3. **Verify your work.** After making changes, run relevant tests or commands to confirm correctness.
+4. **Be concise.** Show code over prose. Explain only what's necessary.
+5. **One step at a time.** For multi-step tasks, execute them sequentially.
+6. **edit_file uniqueness.** When using edit_file, include enough surrounding context in old_string to guarantee a unique match.
+7. **Respect existing style.** Match the project's coding conventions.
+8. **Ask when unsure.** If the request is ambiguous, ask for clarification rather than guessing.
+"""

corecoder/session.py

@@ -0,0 +1,68 @@
+"""Session persistence - save and resume conversations.
+
+Claude Code maintains session state via QueryEngine (1295 lines).
+CoreCoder distills this to: JSON dump of messages + model config.
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+
+SESSIONS_DIR = Path.home() / ".corecoder" / "sessions"
+
+
+def save_session(messages: list[dict], model: str, session_id: str | None = None) -> str:
+    """Save conversation to disk. Returns the session ID."""
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+    if not session_id:
+        session_id = f"session_{int(time.time())}"
+
+    data = {
+        "id": session_id,
+        "model": model,
+        "saved_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "messages": messages,
+    }
+
+    path = SESSIONS_DIR / f"{session_id}.json"
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2))
+    return session_id
+
+
+def load_session(session_id: str) -> tuple[list[dict], str] | None:
+    """Load a saved session. Returns (messages, model) or None."""
+    path = SESSIONS_DIR / f"{session_id}.json"
+    if not path.exists():
+        return None
+
+    data = json.loads(path.read_text())
+    return data["messages"], data["model"]
+
+
+def list_sessions() -> list[dict]:
+    """List available sessions, newest first."""
+    if not SESSIONS_DIR.exists():
+        return []
+
+    sessions = []
+    for f in sorted(SESSIONS_DIR.glob("*.json"), reverse=True):
+        try:
+            data = json.loads(f.read_text())
+            # grab first user message as preview
+            preview = ""
+            for m in data.get("messages", []):
+                if m.get("role") == "user" and m.get("content"):
+                    preview = m["content"][:80]
+                    break
+            sessions.append({
+                "id": data.get("id", f.stem),
+                "model": data.get("model", "?"),
+                "saved_at": data.get("saved_at", "?"),
+                "preview": preview,
+            })
+        except (json.JSONDecodeError, KeyError):
+            continue
+
+    return sessions[:20]  # cap at 20

corecoder/tools/__init__.py

@@ -0,0 +1,27 @@
+"""Tool registry."""
+
+from .bash import BashTool
+from .read import ReadFileTool
+from .write import WriteFileTool
+from .edit import EditFileTool
+from .glob_tool import GlobTool
+from .grep import GrepTool
+from .agent import AgentTool
+
+ALL_TOOLS = [
+    BashTool(),
+    ReadFileTool(),
+    WriteFileTool(),
+    EditFileTool(),
+    GlobTool(),
+    GrepTool(),
+    AgentTool(),
+]
+
+
+def get_tool(name: str):
+    """Look up a tool by name."""
+    for t in ALL_TOOLS:
+        if t.name == name:
+            return t
+    return None

corecoder/tools/agent.py

@@ -0,0 +1,58 @@
+"""Sub-agent spawning (inspired by Claude Code's AgentTool, 1397 lines).
+
+The idea: for complex sub-tasks, spawn an independent agent with its own
+conversation history and tool access. This lets the main agent delegate
+work like "go research this codebase and report back" without polluting
+its own context window.
+
+The sub-agent runs to completion and returns a text summary.
+"""
+
+from .base import Tool
+
+
+class AgentTool(Tool):
+    name = "agent"
+    description = (
+        "Spawn a sub-agent to handle a complex sub-task independently. "
+        "The sub-agent has its own context and tool access. Use this for: "
+        "researching a codebase, implementing a multi-step change in isolation, "
+        "or any task that would benefit from a fresh context window."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "task": {
+                "type": "string",
+                "description": "What the sub-agent should accomplish",
+            },
+        },
+        "required": ["task"],
+    }
+
+    # set by Agent.__init__ after construction
+    _parent_agent = None
+
+    def execute(self, task: str) -> str:
+        if self._parent_agent is None:
+            return "Error: agent tool not initialized (no parent agent)"
+
+        # import here to avoid circular dep
+        from ..agent import Agent
+
+        parent = self._parent_agent
+        sub = Agent(
+            llm=parent.llm,
+            tools=[t for t in parent.tools if t.name != "agent"],  # no recursive agents
+            max_context_tokens=parent.context.max_tokens,
+            max_rounds=20,
+        )
+
+        try:
+            result = sub.chat(task)
+            # trim long results to avoid blowing up parent's context
+            if len(result) > 5000:
+                result = result[:4500] + "\n... (sub-agent output truncated)"
+            return f"[Sub-agent completed]\n{result}"
+        except Exception as e:
+            return f"Sub-agent error: {e}"

corecoder/tools/base.py

@@ -0,0 +1,27 @@
+"""Base class for all tools."""
+
+from abc import ABC, abstractmethod
+
+
+class Tool(ABC):
+    """Minimal tool interface. Subclass this to add new capabilities."""
+
+    name: str
+    description: str
+    parameters: dict  # JSON Schema for the function args
+
+    @abstractmethod
+    def execute(self, **kwargs) -> str:
+        """Run the tool and return a text result."""
+        ...
+
+    def schema(self) -> dict:
+        """OpenAI function-calling schema."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }

corecoder/tools/bash.py

@@ -0,0 +1,115 @@
+"""Shell command execution with safety checks.
+
+Claude Code's BashTool is 1,143 lines. This is the distilled version:
+- Output capture with truncation (head+tail preserved)
+- Timeout support
+- Dangerous command detection
+- Working directory tracking (cd awareness)
+"""
+
+import os
+import re
+import subprocess
+from .base import Tool
+
+# track cwd across commands (Claude Code does this too)
+_cwd: str | None = None
+
+# patterns that could wreck the filesystem or leak secrets
+_DANGEROUS_PATTERNS = [
+    (r"\brm\s+(-\w*)?-r\w*\s+(/|~|\$HOME)", "recursive delete on home/root"),
+    (r"\brm\s+(-\w*)?-rf\s", "force recursive delete"),
+    (r"\bmkfs\b", "format filesystem"),
+    (r"\bdd\s+.*of=/dev/", "raw disk write"),
+    (r">\s*/dev/sd[a-z]", "overwrite block device"),
+    (r"\bchmod\s+(-R\s+)?777\s+/", "chmod 777 on root"),
+    (r":\(\)\s*\{.*:\|:.*\}", "fork bomb"),
+    (r"\bcurl\b.*\|\s*(sudo\s+)?bash", "pipe curl to bash"),
+    (r"\bwget\b.*\|\s*(sudo\s+)?bash", "pipe wget to bash"),
+]
+
+
+class BashTool(Tool):
+    name = "bash"
+    description = (
+        "Execute a shell command. Returns stdout, stderr, and exit code. "
+        "Use this for running tests, installing packages, git operations, etc."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The shell command to run",
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Timeout in seconds (default 120)",
+            },
+        },
+        "required": ["command"],
+    }
+
+    def execute(self, command: str, timeout: int = 120) -> str:
+        global _cwd
+        # safety check
+        warning = _check_dangerous(command)
+        if warning:
+            return f"⚠ Blocked: {warning}\nCommand: {command}\nIf intentional, modify the command to be more specific."
+
+        # use tracked working directory
+        cwd = _cwd or os.getcwd()
+
+        try:
+            proc = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=cwd,
+            )
+
+            # track cd commands so next command runs in the right place
+            if proc.returncode == 0:
+                _update_cwd(command, cwd)
+            out = proc.stdout
+            if proc.stderr:
+                out += f"\n[stderr]\n{proc.stderr}"
+            if proc.returncode != 0:
+                out += f"\n[exit code: {proc.returncode}]"
+            # keep head + tail to preserve the most useful info
+            if len(out) > 15_000:
+                out = (
+                    out[:6000]
+                    + f"\n\n... truncated ({len(out)} chars total) ...\n\n"
+                    + out[-3000:]
+                )
+            return out.strip() or "(no output)"
+        except subprocess.TimeoutExpired:
+            return f"Error: timed out after {timeout}s"
+        except Exception as e:
+            return f"Error running command: {e}"
+
+
+def _check_dangerous(cmd: str) -> str | None:
+    """Return a warning string if the command looks destructive, else None."""
+    for pattern, reason in _DANGEROUS_PATTERNS:
+        if re.search(pattern, cmd):
+            return reason
+    return None
+
+
+def _update_cwd(command: str, current_cwd: str):
+    """Track directory changes from cd commands."""
+    global _cwd
+    # simple heuristic: look for cd at the end of a && chain or standalone
+    parts = command.split("&&")
+    for part in parts:
+        part = part.strip()
+        if part.startswith("cd "):
+            target = part[3:].strip().strip("'\"")
+            if target:
+                new_dir = os.path.normpath(os.path.join(current_cwd, os.path.expanduser(target)))
+                if os.path.isdir(new_dir):
+                    _cwd = new_dir

corecoder/tools/edit.py

@@ -0,0 +1,85 @@
+"""Search-and-replace file editing (Claude Code's key innovation).
+
+The core idea: instead of sending whole-file rewrites or line-number patches,
+the LLM specifies an *exact* substring to find and its replacement. The
+substring must appear exactly once in the file, which eliminates ambiguity
+and makes edits safe and reviewable.
+"""
+
+import difflib
+from pathlib import Path
+
+from .base import Tool
+
+
+class EditFileTool(Tool):
+    name = "edit_file"
+    description = (
+        "Edit a file by replacing an exact string match. "
+        "old_string must appear exactly once in the file for safety. "
+        "Include enough surrounding context to ensure uniqueness."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "Path to the file to edit",
+            },
+            "old_string": {
+                "type": "string",
+                "description": "Exact text to find (must be unique in file)",
+            },
+            "new_string": {
+                "type": "string",
+                "description": "Replacement text",
+            },
+        },
+        "required": ["file_path", "old_string", "new_string"],
+    }
+
+    def execute(self, file_path: str, old_string: str, new_string: str) -> str:
+        try:
+            p = Path(file_path).expanduser().resolve()
+            if not p.exists():
+                return f"Error: {file_path} not found"
+
+            content = p.read_text()
+            occurrences = content.count(old_string)
+
+            if occurrences == 0:
+                preview = content[:500] + ("..." if len(content) > 500 else "")
+                return (
+                    f"Error: old_string not found in {file_path}.\n"
+                    f"File starts with:\n{preview}"
+                )
+            if occurrences > 1:
+                return (
+                    f"Error: old_string appears {occurrences} times in {file_path}. "
+                    f"Include more surrounding lines to make it unique."
+                )
+
+            new_content = content.replace(old_string, new_string, 1)
+            p.write_text(new_content)
+
+            # generate a unified diff so the user/LLM can see exactly what changed
+            diff = _unified_diff(content, new_content, str(p))
+            return f"Edited {file_path}\n{diff}"
+        except Exception as e:
+            return f"Error: {e}"
+
+
+def _unified_diff(old: str, new: str, filename: str, context: int = 3) -> str:
+    """Generate a compact unified diff between old and new file content."""
+    old_lines = old.splitlines(keepends=True)
+    new_lines = new.splitlines(keepends=True)
+    diff = difflib.unified_diff(
+        old_lines, new_lines,
+        fromfile=f"a/{filename}", tofile=f"b/{filename}",
+        n=context,
+    )
+    result = "".join(diff)
+    # truncate enormous diffs
+    if len(result) > 3000:
+        result = result[:2500] + "\n... (diff truncated)\n"
+    return result

corecoder/tools/glob_tool.py

@@ -0,0 +1,47 @@
+"""File pattern matching."""
+
+from pathlib import Path
+from .base import Tool
+
+
+class GlobTool(Tool):
+    name = "glob"
+    description = (
+        "Find files matching a glob pattern. "
+        "Supports ** for recursive matching (e.g. '**/*.py')."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "Glob pattern, e.g. '**/*.py' or 'src/**/*.ts'",
+            },
+            "path": {
+                "type": "string",
+                "description": "Directory to search in (default: cwd)",
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    def execute(self, pattern: str, path: str = ".") -> str:
+        try:
+            base = Path(path).expanduser().resolve()
+            if not base.is_dir():
+                return f"Error: {path} is not a directory"
+
+            hits = list(base.glob(pattern))
+            # sort by mtime, newest first
+            hits.sort(key=lambda p: p.stat().st_mtime if p.exists() else 0, reverse=True)
+
+            total = len(hits)
+            shown = hits[:100]
+            lines = [str(h) for h in shown]
+            result = "\n".join(lines)
+
+            if total > 100:
+                result += f"\n... ({total} matches, showing first 100)"
+            return result or "No files matched."
+        except Exception as e:
+            return f"Error: {e}"