limbo-code 0.1.0__py3-none-any.whl

limbo/__init__.py

@@ -0,0 +1,3 @@
+"""Limbo: a minimal terminal AI coding agent."""
+
+__version__ = "0.1.0"

limbo/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m limbo`."""
+
+from limbo.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

limbo/agent.py

@@ -0,0 +1,456 @@
+"""Agent conversation loop."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import secrets
+import time
+import traceback
+import warnings
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from limbo import __version__
+from limbo.config import Config
+from limbo.history import ToolHistory
+from limbo.history import repair as repair_history
+from limbo.llm.client import LLMClient
+from limbo.models import (
+    CompletionMeta,
+    Message,
+    TextChunk,
+    ThinkingChunk,
+    ToolCallEvent,
+    ToolResult,
+)
+from limbo.sessions import SessionMeta, derive_title, load_session, save_session
+from limbo.tools.registry import ToolRegistry
+from limbo.trace import TraceLogger, trace_path_for
+
+
+@dataclass(frozen=True)
+class TextDelta:
+    text: str
+
+
+@dataclass(frozen=True)
+class ThinkingDelta:
+    """A streamed reasoning/thinking delta (reasoning models only)."""
+
+    text: str
+
+
+@dataclass(frozen=True)
+class ToolCallRequest:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolResultEvent:
+    id: str
+    name: str
+    result: ToolResult
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ErrorEvent:
+    message: str
+
+
+AgentEvent = TextDelta | ThinkingDelta | ToolCallRequest | ToolResultEvent | ErrorEvent
+
+
+def _extract_cached_tokens(usage: dict[str, Any] | None) -> int | None:
+    """Normalize provider-specific prompt cache-hit counters.
+
+    DeepSeek reports ``prompt_cache_hit_tokens``, OpenAI nests
+    ``prompt_tokens_details.cached_tokens``, Anthropic reports
+    ``cache_read_input_tokens``.
+    """
+    if not usage:
+        return None
+    hit = usage.get("prompt_cache_hit_tokens")
+    if isinstance(hit, int):
+        return hit
+    details = usage.get("prompt_tokens_details")
+    if isinstance(details, dict):
+        cached = details.get("cached_tokens")
+        if isinstance(cached, int):
+            return cached
+    read = usage.get("cache_read_input_tokens")
+    return read if isinstance(read, int) else None
+
+
+class Agent:
+    """Orchestrates the conversation between user, LLM, and tools."""
+
+    def __init__(
+        self,
+        config: Config,
+        llm_client: LLMClient,
+        workdir: Path,
+        session_dir: Path | None = None,
+        resume: Path | None = None,
+    ):
+        self.config = config
+        self.llm_client = llm_client
+        self.workdir = workdir
+        self.registry = ToolRegistry(workdir=workdir, config=config)
+        self._history = ToolHistory([])
+        self._iteration_count = 0
+        self._init_system_message()
+
+        self._session_dir = session_dir or Path.home() / ".limbo" / "sessions"
+        if resume is not None:
+            self._meta, history = load_session(resume)
+            self._session_file = resume
+            self.messages.extend(repair_history(history))
+        else:
+            timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+            # Random suffix avoids collisions when sessions are created in
+            # quick succession within the same process (e.g. `/new`).
+            self._session_file = (
+                self._session_dir
+                / f"{timestamp}-{os.getpid()}-{secrets.token_hex(2)}.jsonl"
+            )
+            self._meta = SessionMeta(
+                id=self._session_file.stem,
+                workdir=str(workdir.resolve()),
+                model=config.llm.model,
+                created_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            )
+
+        # Trace log: full-fidelity JSONL record of the run, kept separate from
+        # the resumable session file. Created lazily-tolerant: tracing must
+        # never break the agent.
+        self.trace = TraceLogger(trace_path_for(self._session_file))
+        self._turn_count = 0
+        self._turn_start: float | None = None
+        self.trace.log(
+            "session_start",
+            session_id=self._meta.id,
+            workdir=str(workdir.resolve()),
+            resumed=resume is not None,
+            restored_messages=(len(self.messages) - 1) if resume is not None else 0,
+            limbo_version=__version__,
+            python=platform.python_version(),
+            platform=platform.platform(),
+            config={
+                "model": config.llm.model,
+                "base_url": config.llm.base_url,
+                "temperature": config.llm.temperature,
+                "max_tokens": config.llm.max_tokens,
+                "max_iterations": config.llm.max_iterations,
+                "thinking_effort": config.llm.thinking_effort,
+                "bash_enabled": config.tools.bash_enabled,
+            },
+        )
+
+    @property
+    def session_id(self) -> str:
+        """Stable id of the current session (the session file stem)."""
+        return self._meta.id
+
+    @property
+    def session_meta(self) -> SessionMeta:
+        """Metadata of the current session (title filled in on first save)."""
+        if not self._meta.title:
+            self._meta.title = derive_title(self.messages)
+        return self._meta
+
+    def _init_system_message(self) -> None:
+        content_parts = [
+            (
+                "You are an expert coding assistant operating inside limbo, "
+                "a coding agent harness. You help users by reading files, "
+                "executing commands, editing code, and writing new files.\n\n"
+                "Available tools:\n"
+                "- read: Read file contents\n"
+                "- bash: Execute bash commands\n"
+                "- edit: Make surgical edits to files (find exact text and replace)\n"
+                "- write: Create or overwrite files\n"
+                "- grep: Search file contents for patterns (respects root .gitignore)\n"
+                "- find: Find files by glob pattern (respects root .gitignore only)\n"
+                "- ls: List directory contents\n\n"
+                "Guidelines:\n"
+                "- Prefer grep/find/ls tools over bash for file exploration\n"
+                "- Use read to examine files before editing\n"
+                "- Use edit for precise changes (old_text must match exactly)\n"
+                "- Use write only for new files or complete rewrites\n"
+                "- Be concise in your responses\n"
+                "- Show file paths clearly when working with files"
+            ),
+        ]
+        # Load optional project-level AGENTS.md for extra context.
+        project_md = self.workdir / "AGENTS.md"
+        if project_md.is_file():
+            try:
+                text = project_md.read_text(encoding="utf-8")
+                content_parts.append(
+                    f"\n\n## Project context from AGENTS.md\n\n{text}"
+                )
+            except OSError:
+                pass
+        # Load optional global AGENTS.md for personal preferences.
+        global_md = Path.home() / ".limbo" / "AGENTS.md"
+        if global_md.is_file():
+            try:
+                text = global_md.read_text(encoding="utf-8")
+                content_parts.append(
+                    f"\n\n## User preferences from ~/.limbo/AGENTS.md\n\n{text}"
+                )
+            except OSError:
+                pass
+        self.messages.append(
+            Message(
+                role="system",
+                content="".join(content_parts),
+            )
+        )
+
+    @property
+    def messages(self) -> list[Message]:
+        """The conversation history (owned by the tool-call bookkeeper)."""
+        return self._history.messages
+
+    @messages.setter
+    def messages(self, value: list[Message]) -> None:
+        self._history.messages = value
+
+    def _log_turn_end(self) -> None:
+        if self._turn_start is None:
+            return
+        self.trace.log(
+            "turn_end",
+            turn=self._turn_count,
+            duration=time.monotonic() - self._turn_start,
+            iterations=self._iteration_count,
+            status="completed",
+        )
+        self._turn_start = None
+
+    async def run(self, user_input: str) -> AsyncIterator[AgentEvent]:
+        # Reset per-user-turn state.
+        self._iteration_count = 0
+        self._turn_count += 1
+        self._turn_start = time.monotonic()
+
+        self.messages.append(Message(role="user", content=user_input))
+        self.trace.log(
+            "user_message", turn=self._turn_count, content=user_input
+        )
+
+        try:
+            async for event in self._conversation_loop():
+                yield event
+        finally:
+            self._log_turn_end()
+            try:
+                await self._save_session()
+            except Exception as e:  # noqa: BLE001
+                self.trace.log(
+                    "session_save_error", turn=self._turn_count, error=str(e)
+                )
+                warnings.warn(f"Failed to save session: {e}", stacklevel=2)
+
+    async def _execute_tool(
+        self,
+        call_id: str,
+        name: str,
+        arguments: dict[str, Any],
+    ) -> ToolResult:
+        """Execute a tool with full trace logging. Re-raises on crash."""
+        self.trace.log(
+            "tool_call",
+            turn=self._turn_count,
+            iteration=self._iteration_count,
+            id=call_id,
+            name=name,
+            arguments=arguments,
+        )
+        start = time.monotonic()
+        try:
+            result = await self.registry.execute(name, arguments)
+        except Exception as e:  # noqa: BLE001
+            self.trace.log(
+                "tool_result",
+                turn=self._turn_count,
+                iteration=self._iteration_count,
+                id=call_id,
+                name=name,
+                success=False,
+                error=f"Tool error: {e}",
+                exception_type=type(e).__name__,
+                traceback=traceback.format_exc(),
+                duration=time.monotonic() - start,
+            )
+            raise
+        self.trace.log(
+            "tool_result",
+            turn=self._turn_count,
+            iteration=self._iteration_count,
+            id=call_id,
+            name=name,
+            success=result.success,
+            output=result.output,
+            error=result.error,
+            duration=time.monotonic() - start,
+        )
+        return result
+
+    async def _conversation_loop(self) -> AsyncIterator[AgentEvent]:
+        while self._iteration_count < self.config.llm.max_iterations:
+            self._iteration_count += 1
+            try:
+                async for event in self._call_llm():
+                    yield event
+            except Exception as e:  # noqa: BLE001
+                self.trace.log(
+                    "llm_error",
+                    turn=self._turn_count,
+                    iteration=self._iteration_count,
+                    error=str(e),
+                    exception_type=type(e).__name__,
+                    traceback=traceback.format_exc(),
+                )
+                yield ErrorEvent(message=f"LLM error: {e}")
+                return
+
+            last = self.messages[-1]
+            if not last.tool_calls:
+                break
+
+            # If we've reached the iteration limit on an assistant message that
+            # requests tool calls, cancel the calls instead of executing them.
+            # OpenAI requires a matching ``role="tool"`` result for every
+            # ``tool_call_id`` referenced by the assistant.
+            if self._iteration_count >= self.config.llm.max_iterations:
+                for tc in last.tool_calls:
+                    self.messages.append(
+                        Message(
+                            role="tool",
+                            content="Maximum iteration count reached; tool not executed.",
+                            tool_call_id=tc["id"],
+                        )
+                    )
+                self.trace.log(
+                    "error",
+                    turn=self._turn_count,
+                    kind="max_iterations",
+                    message="Maximum iteration count reached; remaining tool calls were cancelled.",
+                    cancelled_tool_call_ids=[tc["id"] for tc in last.tool_calls],
+                )
+                yield ErrorEvent(
+                    message="Maximum iteration count reached; remaining tool calls were cancelled."
+                )
+                break
+
+            for idx, tc in enumerate(last.tool_calls):
+                name = tc["function"]["name"]
+                arguments = tc["function"]["arguments"]
+                yield ToolCallRequest(id=tc["id"], name=name, arguments=arguments)
+                try:
+                    result = await self._execute_tool(tc["id"], name, arguments)
+                except Exception as e:  # noqa: BLE001
+                    error_message = f"Tool error: {e}"
+                    yield ErrorEvent(message=error_message)
+                    self._history.record_error(
+                        last, idx, tc["id"], error_message
+                    )
+                    return
+                yield ToolResultEvent(
+                    id=tc["id"], name=name, result=result, arguments=arguments
+                )
+                self._history.record_result(
+                    tc["id"], result.output or result.error or ""
+                )
+
+    async def _call_llm(self) -> AsyncIterator[AgentEvent]:
+        tool_definitions = self.registry.definitions()
+        assistant_content = ""
+        assistant_reasoning = ""
+        assistant_signature: str | None = None
+        tool_calls: list[dict[str, Any]] = []
+        meta: CompletionMeta | None = None
+
+        def _trace_request(body: dict[str, Any]) -> None:
+            self.trace.log(
+                "llm_request",
+                turn=self._turn_count,
+                iteration=self._iteration_count,
+                body=body,
+            )
+
+        async for event in self.llm_client.chat(
+            self.messages, tools=tool_definitions, on_request=_trace_request
+        ):
+            if isinstance(event, TextChunk):
+                assistant_content += event.text
+                yield TextDelta(text=event.text)
+            elif isinstance(event, ThinkingChunk):
+                assistant_reasoning += event.text
+                if event.signature is not None:
+                    assistant_signature = event.signature
+                yield ThinkingDelta(text=event.text)
+            elif isinstance(event, ToolCallEvent):
+                tool_calls.append(
+                    {
+                        "id": event.id,
+                        "type": "function",
+                        "function": {
+                            "name": event.name,
+                            "arguments": event.arguments,
+                        },
+                    }
+                )
+                yield ToolCallRequest(
+                    id=event.id, name=event.name, arguments=event.arguments
+                )
+            elif isinstance(event, CompletionMeta):
+                meta = event
+
+        usage = meta.usage if meta else None
+        self.trace.log(
+            "llm_response",
+            turn=self._turn_count,
+            iteration=self._iteration_count,
+            duration=meta.duration if meta else None,
+            ttft=meta.ttft if meta else None,
+            finish_reason=meta.finish_reason if meta else None,
+            usage=usage,
+            cached_tokens=_extract_cached_tokens(usage),
+            content_chars=len(assistant_content),
+            reasoning_chars=len(assistant_reasoning),
+            tool_calls=[
+                {"id": tc["id"], "name": tc["function"]["name"]}
+                for tc in tool_calls
+            ],
+        )
+
+        self.messages.append(
+            Message(
+                role="assistant",
+                content=assistant_content or None,
+                tool_calls=tool_calls if tool_calls else None,
+                reasoning=assistant_reasoning or None,
+                reasoning_signature=assistant_signature,
+            )
+        )
+
+    def _save_session_sync(self) -> None:
+        # Rewrite the whole session on every save. It is cheap for MVP-sized
+        # conversations.
+        if not self._meta.title:
+            self._meta.title = derive_title(self.messages)
+        save_session(self._session_file, self._meta, self.messages)
+
+    async def _save_session(self) -> None:
+        await asyncio.to_thread(self._save_session_sync)

limbo/app.py

@@ -0,0 +1,107 @@
+"""CLI entry point for Limbo."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from limbo.config import load_config
+from limbo.llm.catalog import resolve_api_key, resolve_model
+from limbo.sessions import (
+    AmbiguousSessionError,
+    SessionNotFoundError,
+    find_session,
+    latest_session,
+    load_session,
+)
+from limbo.ui.app import LimboApp
+
+DEFAULT_SESSION_DIR = Path.home() / ".limbo" / "sessions"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Limbo TUI coding agent")
+    parser.add_argument(
+        "--workdir",
+        type=Path,
+        default=Path.cwd(),
+        help="Working directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--session-dir",
+        type=Path,
+        default=None,
+        help="Directory for session JSONL files (default: ~/.limbo/sessions)",
+    )
+    resume_group = parser.add_mutually_exclusive_group()
+    resume_group.add_argument(
+        "--continue",
+        dest="continue_session",
+        action="store_true",
+        help="Resume the most recent session for the working directory",
+    )
+    resume_group.add_argument(
+        "--resume",
+        metavar="SESSION_ID",
+        default=None,
+        help="Resume a session by id (or unique id prefix)",
+    )
+    args = parser.parse_args()
+
+    config = load_config()
+    spec = resolve_model(config.llm.model)
+    if not resolve_api_key(spec, config.llm.api_key):
+        env_hint = (
+            f" or ${spec.provider.api_key_env}"
+            if spec.provider.api_key_env
+            else ""
+        )
+        print(
+            "Error: No API key configured. Set it in ~/.limbo/config.toml\n"
+            f"  [llm]\n  api_key = 'your-key'{env_hint}",
+            file=sys.stderr,
+        )
+        return 1
+
+    session_dir = args.session_dir or DEFAULT_SESSION_DIR
+    workdir = args.workdir
+    resume: Path | None = None
+
+    if args.continue_session:
+        resume = latest_session(session_dir, workdir=workdir)
+        if resume is None:
+            print(
+                f"Error: No session to continue for {workdir.resolve()}",
+                file=sys.stderr,
+            )
+            return 1
+    elif args.resume is not None:
+        try:
+            resume = find_session(session_dir, args.resume)
+        except SessionNotFoundError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 1
+        except AmbiguousSessionError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 1
+
+    if resume is not None:
+        # The session's recorded workdir wins when it still exists — sessions
+        # are bound to the project they were created in.
+        meta, _ = load_session(resume)
+        if meta.workdir and Path(meta.workdir).is_dir():
+            workdir = Path(meta.workdir)
+
+    app = LimboApp(
+        workdir=workdir,
+        config=config,
+        session_dir=args.session_dir,
+        resume=resume,
+    )
+    app.run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

limbo/config.py

@@ -0,0 +1,99 @@
+"""Configuration loading for Limbo."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Any
+
+import toml  # type: ignore[import-untyped]
+from pydantic import BaseModel, Field, ValidationError, field_validator
+from toml import TomlDecodeError
+
+DEFAULT_CONFIG_PATH = Path.home() / ".limbo" / "config.toml"
+
+# Single source of truth for safety defaults; tools fall back to these when
+# constructed without explicit values.
+DEFAULT_DANGEROUS_COMMANDS = ["rm", "git reset --hard"]
+DEFAULT_SENSITIVE_FILES = [".env", "id_rsa", "id_ed25519", ".ssh"]
+
+
+class LLMConfig(BaseModel):
+    api_key: str | None = None
+    base_url: str = "https://api.deepseek.com/v1"
+    model: str = "deepseek-chat"
+    temperature: float = 0.2
+    max_iterations: int = 10
+    # Thinking control for reasoning models (e.g. kimi-k3: low|high|max,
+    # deepseek-format Kimi models: on value or "off"). None = provider default.
+    thinking_effort: str | None = None
+    # Per-request output token cap; None = use the model catalog default.
+    max_tokens: int | None = None
+
+    @field_validator("max_iterations")
+    @classmethod
+    def _max_iterations_must_be_positive(cls, value: int) -> int:
+        if value < 1:
+            raise ValueError("max_iterations must be at least 1")
+        return value
+
+    @field_validator("max_tokens")
+    @classmethod
+    def _max_tokens_must_be_positive(cls, value: int | None) -> int | None:
+        if value is not None and value < 1:
+            raise ValueError("max_tokens must be at least 1")
+        return value
+
+
+class UIConfig(BaseModel):
+    # Textual built-in theme name, e.g. "textual-dark", "dracula", "nord".
+    theme: str | None = None
+
+
+class SafetyConfig(BaseModel):
+    dangerous_commands: list[str] = Field(
+        default_factory=lambda: list(DEFAULT_DANGEROUS_COMMANDS)
+    )
+    sensitive_files: list[str] = Field(
+        default_factory=lambda: list(DEFAULT_SENSITIVE_FILES)
+    )
+
+
+class ToolsConfig(BaseModel):
+    bash_enabled: bool = True
+
+
+class Config(BaseModel):
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    ui: UIConfig = Field(default_factory=UIConfig)
+    safety: SafetyConfig = Field(default_factory=SafetyConfig)
+    tools: ToolsConfig = Field(default_factory=ToolsConfig)
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Load config from TOML file, falling back to defaults."""
+    path = path or DEFAULT_CONFIG_PATH
+    if not path.exists():
+        return Config()
+    try:
+        data: dict[str, Any] = toml.load(path)
+    except TomlDecodeError as e:
+        warnings.warn(
+            f"Malformed config file {path}: {e}. Using defaults.",
+            stacklevel=2,
+        )
+        return Config()
+    except OSError as e:
+        warnings.warn(
+            f"Could not read config file {path}: {e}. Using defaults.",
+            stacklevel=2,
+        )
+        return Config()
+    try:
+        return Config.model_validate(data)
+    except ValidationError as e:
+        warnings.warn(
+            f"Invalid config file {path}: {e}. Using defaults.",
+            stacklevel=2,
+        )
+        return Config()