vtx-coding-agent 0.1.1__py3-none-any.whl

vtx/loop.py

@@ -0,0 +1,272 @@
+"""
+Run the agent loop and stream events for the UI.
+
+Each turn runs `run_single_turn()`, forwards turn/tool events immediately, persists assistant/tool
+messages to the session, and decides whether to continue. After every turn, overflow compaction
+may run and emit its own start/end events so the UI can reflect that state in real time.
+
+The loop ends on stop/error/interruption, compaction pause mode, or max turns.
+"""
+
+import asyncio
+import os
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+from . import config as vtx_config
+from .context import Context
+from .core.compaction import generate_summary, is_overflow
+from .core.errors import format_error
+from .core.types import (
+    AssistantMessage,
+    ImageContent,
+    Message,
+    StopReason,
+    TextContent,
+    ToolResultMessage,
+    Usage,
+    UserMessage,
+)
+from .events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    CompactionEndEvent,
+    CompactionStartEvent,
+    ErrorEvent,
+    Event,
+    InterruptedEvent,
+    TurnEndEvent,
+    TurnStartEvent,
+)
+from .llm import BaseProvider
+from .prompts import build_system_prompt
+from .session import MessageEntry, Session
+from .tools import BaseTool
+from .turn import run_single_turn
+
+# Re-exported so existing callers (runtime, tests) keep working.
+__all__ = ["Agent", "AgentConfig", "build_system_prompt"]
+
+
+@dataclass
+class AgentConfig:
+    context_window: int | None = None
+    max_output_tokens: int | None = None
+
+
+class Agent:
+    def __init__(
+        self,
+        provider: BaseProvider,
+        tools: list[BaseTool],
+        session: Session,
+        cwd: str | None = None,
+        context: Context | None = None,
+        system_prompt: str | None = None,
+        config: AgentConfig | None = None,
+    ):
+        self.provider = provider
+        self.tools = tools
+        self.session = session
+        self.config = config or AgentConfig()
+        self._cwd = cwd or os.getcwd()
+        self._context = context or Context.load(self._cwd)
+        self._system_prompt = system_prompt or build_system_prompt(
+            self._cwd, self._context, tools=tools
+        )
+        self._run_usage = Usage()
+
+    @property
+    def context(self) -> Context:
+        return self._context
+
+    @property
+    def system_prompt(self) -> str:
+        return self._system_prompt
+
+    def reload_context(self) -> None:
+        self._context = Context.load(self._cwd)
+        self._system_prompt = build_system_prompt(self._cwd, self._context, tools=self.tools)
+
+    @property
+    def messages(self) -> list[Message]:
+        return self.session.messages
+
+    def _add_usage(self, usage: Usage | None) -> None:
+        if usage:
+            self._run_usage.input_tokens += usage.input_tokens
+            self._run_usage.output_tokens += usage.output_tokens
+            self._run_usage.cache_read_tokens += usage.cache_read_tokens
+            self._run_usage.cache_write_tokens += usage.cache_write_tokens
+
+    async def run(
+        self,
+        query: str,
+        images: list[ImageContent] | None = None,
+        cancel_event: asyncio.Event | None = None,
+        steer_event: asyncio.Event | None = None,
+    ) -> AsyncIterator[Event]:
+        self._run_usage = Usage()
+
+        if images:
+            user_content: list[TextContent | ImageContent] = [TextContent(text=query), *images]
+            user_message = UserMessage(content=user_content)
+        else:
+            user_message = UserMessage(content=query)
+
+        self.session.append_message(user_message)
+
+        yield AgentStartEvent()
+
+        turn = 0
+        stop_reason = StopReason.STOP
+        was_interrupted = False
+
+        system_prompt = self._system_prompt
+
+        try:
+            max_turns = vtx_config.agent.max_turns
+            while turn < max_turns:
+                if cancel_event and cancel_event.is_set():
+                    was_interrupted = True
+                    stop_reason = StopReason.INTERRUPTED
+                    yield InterruptedEvent(message="Interrupted by user")
+                    break
+
+                if steer_event and steer_event.is_set():
+                    stop_reason = StopReason.STEER
+                    break
+
+                turn += 1
+                yield TurnStartEvent(turn=turn)
+
+                messages = self.session.messages
+                tool_results: list[ToolResultMessage] = []
+                async for event in run_single_turn(
+                    provider=self.provider,
+                    messages=messages,
+                    tools=self.tools,
+                    system_prompt=system_prompt,
+                    turn=turn,
+                    cancel_event=cancel_event,
+                ):
+                    yield event
+
+                    if isinstance(event, TurnEndEvent):
+                        if event.assistant_message:
+                            self._add_usage(event.assistant_message.usage)
+                            self.session.append_message(event.assistant_message)
+                        tool_results = event.tool_results
+                        stop_reason = event.stop_reason
+                        for result in tool_results:
+                            self.session.append_message(result)
+                    elif isinstance(event, InterruptedEvent):
+                        was_interrupted = True
+
+                if was_interrupted or stop_reason == StopReason.INTERRUPTED:
+                    stop_reason = StopReason.INTERRUPTED
+                    break
+
+                if steer_event and steer_event.is_set():
+                    stop_reason = StopReason.STEER
+                    break
+
+                # Check for context overflow after each turn.
+                # We iterate events instead of awaiting a single compaction result so
+                # CompactionStartEvent can be forwarded immediately and the UI can
+                # render a "compacting" state while summary generation is running.
+                did_compact = False
+                async for compaction_event in self._check_compaction(
+                    stop_reason, system_prompt, cancel_event
+                ):
+                    yield compaction_event
+                    if isinstance(compaction_event, CompactionEndEvent):
+                        did_compact = True
+                if did_compact:
+                    if vtx_config.compaction.on_overflow == "pause":
+                        break
+                    # Continue mode: synthetic user message was injected, continue loop
+                    continue
+
+                if stop_reason != StopReason.TOOL_USE:
+                    break
+
+            if turn >= max_turns and not was_interrupted and stop_reason == StopReason.TOOL_USE:
+                stop_reason = StopReason.LENGTH
+
+        except Exception as e:  # intentionally broad — top-level boundary; crash = broken TUI
+            yield ErrorEvent(error=format_error(e))
+            stop_reason = StopReason.ERROR
+
+        yield AgentEndEvent(stop_reason=stop_reason, total_turns=turn, total_usage=self._run_usage)
+
+    async def _check_compaction(
+        self, stop_reason: StopReason, system_prompt: str, cancel_event: asyncio.Event | None
+    ) -> AsyncIterator[CompactionStartEvent | CompactionEndEvent]:
+        if stop_reason == StopReason.ERROR:
+            return
+
+        # Get the latest assistant message that has usage.
+        # The most recent assistant entry can be interrupted/error and have no usage.
+        last_usage: Usage | None = None
+        for entry in reversed(self.session.active_entries):
+            if isinstance(entry, MessageEntry) and isinstance(entry.message, AssistantMessage):
+                usage = entry.message.usage
+                if usage is None:
+                    continue
+                last_usage = usage
+                break
+
+        if last_usage is None:
+            return
+
+        context_window = self.config.context_window or vtx_config.agent.default_context_window
+        max_output = self.config.max_output_tokens or self.provider.config.max_tokens or 0
+        buffer_tokens = vtx_config.compaction.buffer_tokens
+
+        if not is_overflow(last_usage, context_window, max_output, buffer_tokens):
+            return
+
+        if cancel_event and cancel_event.is_set():
+            return
+
+        tokens_before = (
+            last_usage.input_tokens
+            + last_usage.output_tokens
+            + last_usage.cache_read_tokens
+            + last_usage.cache_write_tokens
+        )
+
+        # Yield start event immediately so UI can show status
+        yield CompactionStartEvent()
+
+        try:
+            # Use all_messages (uncompacted) for summarization so LLM sees full history
+            summary = await generate_summary(
+                self.session.all_messages, self.provider, system_prompt
+            )
+
+            # Everything before is summarized, nothing "kept"
+            first_kept_id = self.session.leaf_id or ""
+
+            self.session.append_compaction(
+                summary=summary, first_kept_entry_id=first_kept_id, tokens_before=tokens_before
+            )
+
+            # In continue mode, inject synthetic continue message
+            if vtx_config.compaction.on_overflow == "continue":
+                continue_msg = UserMessage(
+                    content=(
+                        "Continue if you have next steps, or stop and ask for clarification if you"
+                        " are unsure how to proceed. If there is nothing to do don't add a large"
+                        " preamble, just summarise everything so far in 2-3 lines and be done."
+                    )
+                )
+                self.session.append_message(continue_msg)
+
+            yield CompactionEndEvent(tokens_before=tokens_before)
+
+        except Exception as e:
+            yield CompactionEndEvent(
+                tokens_before=tokens_before, aborted=True, reason=format_error(e)
+            )

vtx/notify.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from functools import cache
+from importlib import resources
+from pathlib import Path
+from typing import Literal
+
+from vtx import config
+
+NotificationEvent = Literal["completion", "permission", "error"]
+
+_SOUND_FILES: dict[NotificationEvent, str] = {
+    "completion": "completion.wav",
+    "permission": "permission.wav",
+    "error": "error.wav",
+}
+
+
+@cache
+def _platform() -> str:
+    return platform.system().lower()
+
+
+@cache
+def _sound_path(event: NotificationEvent) -> Path:
+    return Path(str(resources.files("vtx.sounds").joinpath(_SOUND_FILES[event])))
+
+
+@cache
+def _linux_player() -> str | None:
+    for player in ("paplay", "aplay", "mpv", "ffplay"):
+        if shutil.which(player):
+            return player
+    return None
+
+
+def _run(command: list[str]) -> None:
+    subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+def _play_macos(sound_path: Path, volume: float) -> None:
+    _run(["afplay", "-v", str(volume), str(sound_path)])
+
+
+def _play_linux(sound_path: Path, volume: float) -> None:
+    player = _linux_player()
+    if player is None:
+        return
+
+    sound = str(sound_path)
+    match player:
+        case "paplay":
+            _run(["paplay", f"--volume={round(volume * 65536)}", sound])
+        case "aplay":
+            _run(["aplay", sound])
+        case "mpv":
+            _run(
+                [
+                    "mpv",
+                    "--no-video",
+                    "--no-terminal",
+                    "--script-opts=autoload-disabled=yes",
+                    f"--volume={volume * 100}",
+                    sound,
+                ]
+            )
+        case "ffplay":
+            _run(
+                [
+                    "ffplay",
+                    "-nodisp",
+                    "-autoexit",
+                    "-loglevel",
+                    "quiet",
+                    "-volume",
+                    str(round(volume * 100)),
+                    sound,
+                ]
+            )
+
+
+def _play_windows(sound_path: Path, volume: float) -> None:
+    # NOTE volume IGNORED!
+    _run(
+        [
+            "powershell",
+            "-c",
+            "(New-Object Media.SoundPlayer '" + str(sound_path) + "').PlaySync();",
+        ]
+    )
+
+
+def notify(event: NotificationEvent) -> None:
+    sound_path = _sound_path(event)
+    volume = config.notifications.volume
+    os_name = _platform()
+
+    try:
+        if os_name == "darwin":
+            _play_macos(sound_path, volume)
+        elif os_name == "linux":
+            _play_linux(sound_path, volume)
+        elif os_name == "windows":
+            _play_windows(sound_path, volume)
+    except Exception:
+        return

vtx/permissions.py

@@ -0,0 +1,114 @@
+import shlex
+from enum import Enum
+
+from vtx import config
+
+from .tools.base import BaseTool
+
+
+class PermissionDecision(Enum):
+    ALLOW = "allow"
+    PROMPT = "prompt"
+
+
+class ApprovalResponse(Enum):
+    APPROVE = "approve"
+    DENY = "deny"
+
+
+SAFE_COMMANDS: frozenset[str] = frozenset(
+    {
+        "cat",
+        "head",
+        "tail",
+        "ls",
+        "pwd",
+        "wc",
+        "diff",
+        "which",
+        "file",
+        "stat",
+        "du",
+        "df",
+        "whoami",
+        "id",
+        "uname",
+        "date",
+        "realpath",
+        "dirname",
+        "basename",
+    }
+)
+
+SAFE_GIT_SUBCOMMANDS: frozenset[str] = frozenset(
+    {
+        "status",
+        "diff",
+        "log",
+        "show",
+        "rev-parse",
+        "describe",
+        "ls-files",
+        "ls-tree",
+        "blame",
+        "shortlog",
+    }
+)
+
+_PUNCTUATION_CHARS = frozenset(";|&()><")
+
+
+def check_permission(tool: BaseTool, arguments: dict) -> PermissionDecision:
+    if config.permissions.mode == "auto":
+        return PermissionDecision.ALLOW
+    if not tool.mutating:
+        return PermissionDecision.ALLOW
+    if tool.name == "bash":
+        command = arguments.get("command", "")
+        if _is_safe_bash_command(command):
+            return PermissionDecision.ALLOW
+    return PermissionDecision.PROMPT
+
+
+def _is_safe_bash_command(command: str) -> bool:
+    if "\n" in command or "`" in command or "$(" in command or "<(" in command or ">(" in command:
+        return False
+
+    try:
+        lexer = shlex.shlex(command, posix=True, punctuation_chars=";|&()><")
+        tokens = list(lexer)
+    except ValueError:
+        return False
+
+    if not tokens:
+        return False
+
+    for token in tokens:
+        if token and all(c in _PUNCTUATION_CHARS for c in token):
+            return False
+
+    base = tokens[0]
+    if "/" in base:
+        base = base.rsplit("/", 1)[-1]
+
+    if base == "git":
+        return _is_safe_git_command(tokens)
+
+    return base in SAFE_COMMANDS
+
+
+def _is_safe_git_command(tokens: list[str]) -> bool:
+    i = 1
+    while i < len(tokens):
+        if tokens[i] in ("-c", "--config-env") or tokens[i].startswith("--config-env="):
+            return False
+        if not tokens[i].startswith("-"):
+            if tokens[i] not in SAFE_GIT_SUBCOMMANDS:
+                return False
+            # --output writes diff to a file, making it mutating
+            return not any(t == "--output" or t.startswith("--output=") for t in tokens[i + 1 :])
+        if tokens[i] in ("-C", "--git-dir", "--work-tree", "--namespace") and i + 1 < len(tokens):
+            i += 2
+            continue
+        i += 1
+    return False

vtx/prompts/__init__.py

@@ -0,0 +1,45 @@
+"""System prompt package for Vtx.
+
+Public surface mirrors the JARVIS ``core/agents/prompts`` layout:
+composable string constants in :mod:`vtx.prompts.identity`, per-section
+builders in :mod:`vtx.prompts.tooling` and :mod:`vtx.prompts.env`, and
+the orchestrator in :mod:`vtx.prompts.builder`.
+"""
+
+from .builder import build_system_prompt
+from .env import ENV_HEADER, build_env_section
+from .identity import (
+    CONTEXT_AWARENESS,
+    DEFAULT_VTX_BASE,
+    EDITING_CONSTRAINTS,
+    ERROR_RECOVERY,
+    EXECUTION_DISCIPLINE,
+    OUTPUT_FORMATTING,
+    PROGRESS_UPDATES,
+    SAFETY,
+    TASK_COMPLETION,
+    TOOL_USE_ENFORCEMENT,
+    VTX_GENERAL_RULES,
+    VTX_IDENTITY,
+)
+from .tooling import TOOL_USAGE_HEADER, build_tool_guidelines_section
+
+__all__ = [
+    "CONTEXT_AWARENESS",
+    "DEFAULT_VTX_BASE",
+    "EDITING_CONSTRAINTS",
+    "ENV_HEADER",
+    "ERROR_RECOVERY",
+    "EXECUTION_DISCIPLINE",
+    "OUTPUT_FORMATTING",
+    "PROGRESS_UPDATES",
+    "SAFETY",
+    "TASK_COMPLETION",
+    "TOOL_USAGE_HEADER",
+    "TOOL_USE_ENFORCEMENT",
+    "VTX_GENERAL_RULES",
+    "VTX_IDENTITY",
+    "build_env_section",
+    "build_system_prompt",
+    "build_tool_guidelines_section",
+]

vtx/prompts/builder.py

@@ -0,0 +1,86 @@
+"""System prompt assembly for Vtx.
+
+The composer joins a small set of named sections in a fixed order:
+
+1. **base**    - the agent identity + general rules (or a user override)
+2. **tooling** - ``# Tool usage`` lines aggregated from tool guidelines
+3. **project** - discovered ``AGENTS.md`` / ``CLAUDE.md`` files
+4. **skills**  - discovered skill descriptions
+5. **git**     - snapshot of the working tree (only when enabled)
+6. **env**     - current date/time and working directory
+
+Each section is empty when its source has nothing to contribute, so
+the final prompt is just whatever joined list comes back. ``build_system_prompt``
+is the single entry point used by :mod:`vtx.loop` and the runtime.
+"""
+
+from __future__ import annotations
+
+from .. import config as vtx_config
+from ..context import Context, formatted_agent_mds, formatted_git_context, formatted_skills
+from ..tools import BaseTool
+from .env import build_env_section
+from .identity import DEFAULT_VTX_BASE
+from .tooling import build_tool_guidelines_section
+
+
+def _resolve_base(override: str | None) -> str:
+    """Pick the user override, the config value, or the Python default."""
+    if override is not None:
+        return override
+    configured = vtx_config.llm.system_prompt.content
+    return configured if configured else DEFAULT_VTX_BASE
+
+
+def _resolve_git_flag(include_git: bool | None) -> bool:
+    if include_git is not None:
+        return include_git
+    return vtx_config.llm.system_prompt.git_context
+
+
+def build_system_prompt(
+    cwd: str,
+    context: Context | None = None,
+    tools: list[BaseTool] | None = None,
+    *,
+    base_content: str | None = None,
+    include_git_context: bool | None = None,
+) -> str:
+    """Compose the final system prompt for the agent.
+
+    Args:
+        cwd: Working directory used for context discovery and the env line.
+        context: Pre-loaded :class:`Context`. Loaded from ``cwd`` when omitted.
+        tools: Active tool set; contributes the ``# Tool usage`` section.
+        base_content: Override for the base identity/rules string. When
+            ``None`` the function falls back to ``vtx_config.llm.system_prompt.content``
+            and finally :data:`vtx.prompts.identity.DEFAULT_VTX_BASE`.
+        include_git_context: Force the git section on/off. When ``None``
+            the value is read from config.
+    """
+    if context is None:
+        context = Context.load(cwd)
+
+    sections: list[str] = [_resolve_base(base_content)]
+
+    tool_section = build_tool_guidelines_section(tools)
+    if tool_section:
+        sections.append(tool_section)
+
+    if context.agents_files:
+        sections.append(formatted_agent_mds(context.agents_files))
+
+    if context.skills:
+        sections.append(formatted_skills(context.skills))
+
+    if _resolve_git_flag(include_git_context):
+        git_section = formatted_git_context(cwd)
+        if git_section:
+            sections.append(git_section)
+
+    sections.append(build_env_section(cwd))
+
+    return "\n\n".join(sections)
+
+
+__all__ = ["build_system_prompt"]

vtx/prompts/env.py

@@ -0,0 +1,58 @@
+"""Environment section for the system prompt.
+
+Mirrors JARVIS's ``enhance_prompt_with_env_details`` helper: a small
+``# Env`` block with the live execution context the model should know
+about, including the working directory, project root, OS, Python
+version, and the running vtx build.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import platform
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from ..version import VERSION as VTX_VERSION
+
+ENV_HEADER = "# Env"
+
+
+def _find_project_root(start: Path) -> Path:
+    """Walk up from ``start`` until a ``.git`` directory is found.
+
+    Falls back to the starting directory if no git root exists, which
+    matches the behavior of JARVIS's ``get_project_root``.
+    """
+    current = start
+    while current.parent != current and not (current / ".git").exists():
+        current = current.parent
+    return current
+
+
+def _format_env_details(cwd: str) -> str:
+    cwd_path = Path(cwd)
+    project_root = _find_project_root(cwd_path)
+    os_release = platform.system() or "unknown"
+    with contextlib.suppress(Exception):
+        os_release = f"{platform.system()} {platform.release()}".strip()
+
+    return "\n".join(
+        [
+            f"- Date and time: {datetime.now().strftime('%A, %B %d, %Y at %I:%M %p %Z').strip()}",
+            f"- Working directory: {cwd_path}",
+            f"- Project root: {project_root}",
+            f"- OS: {os_release}",
+            f"- Python: {sys.version.split()[0]}",
+            f"- Vtx version: {VTX_VERSION}",
+        ]
+    )
+
+
+def build_env_section(cwd: str) -> str:
+    """Return the ``# Env`` section for ``cwd``."""
+    return f"{ENV_HEADER}\n\n{_format_env_details(cwd)}"
+
+
+__all__ = ["ENV_HEADER", "build_env_section"]