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

vtx/events.py

@@ -0,0 +1,224 @@
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from .core.types import AssistantMessage, FileChanges, StopReason, ToolResultMessage, Usage
+from .permissions import ApprovalResponse
+
+# =================================================================================================
+# Agent Lifecycle Events
+# =================================================================================================
+
+
+@dataclass
+class AgentStartEvent:
+    type: Literal["agent_start"] = "agent_start"
+
+
+@dataclass
+class AgentEndEvent:
+    type: Literal["agent_end"] = "agent_end"
+    stop_reason: StopReason = StopReason.STOP
+    total_turns: int = 0
+    total_usage: Usage | None = None
+
+
+# =================================================================================================
+# Turn Lifecycle Events
+# =================================================================================================
+
+
+@dataclass
+class TurnStartEvent:
+    type: Literal["turn_start"] = "turn_start"
+    turn: int = 0
+
+
+@dataclass
+class TurnEndEvent:
+    type: Literal["turn_end"] = "turn_end"
+    turn: int = 0
+    assistant_message: AssistantMessage | None = None
+    tool_results: list[ToolResultMessage] = field(default_factory=list)
+    stop_reason: StopReason = StopReason.STOP
+    tool_call_count: int = 0
+
+
+# =================================================================================================
+# Content Streaming Events
+# =================================================================================================
+
+
+@dataclass
+class ThinkingStartEvent:
+    type: Literal["thinking_start"] = "thinking_start"
+
+
+@dataclass
+class ThinkingDeltaEvent:
+    type: Literal["thinking_delta"] = "thinking_delta"
+    delta: str = ""
+
+
+@dataclass
+class ThinkingEndEvent:
+    type: Literal["thinking_end"] = "thinking_end"
+    thinking: str = ""
+    signature: str | None = None
+
+
+@dataclass
+class TextStartEvent:
+    type: Literal["text_start"] = "text_start"
+
+
+@dataclass
+class TextDeltaEvent:
+    type: Literal["text_delta"] = "text_delta"
+    delta: str = ""
+
+
+@dataclass
+class TextEndEvent:
+    type: Literal["text_end"] = "text_end"
+    text: str = ""
+
+
+# =================================================================================================
+# Tool Events
+# =================================================================================================
+
+
+@dataclass
+class ToolStartEvent:
+    type: Literal["tool_start"] = "tool_start"
+    tool_call_id: str = ""
+    tool_name: str = ""
+
+
+@dataclass
+class ToolArgsDeltaEvent:
+    type: Literal["tool_args_delta"] = "tool_args_delta"
+    tool_call_id: str = ""
+    delta: str = ""
+
+
+@dataclass
+class ToolArgsTokenUpdateEvent:
+    type: Literal["tool_args_token_update"] = "tool_args_token_update"
+    tool_call_id: str = ""
+    tool_name: str = ""
+    token_count: int = 0
+
+
+@dataclass
+class ToolEndEvent:
+    type: Literal["tool_end"] = "tool_end"
+    tool_call_id: str = ""
+    tool_name: str = ""
+    arguments: dict[str, Any] = field(default_factory=dict)
+    display: str = ""  # Formatted display string from tool.format_call()
+
+
+@dataclass
+class ToolResultEvent:
+    type: Literal["tool_result"] = "tool_result"
+    tool_call_id: str = ""
+    tool_name: str = ""
+    result: ToolResultMessage | None = None
+    file_changes: FileChanges | None = None
+
+
+@dataclass
+class ToolApprovalEvent:
+    type: Literal["tool_approval"] = "tool_approval"
+    tool_call_id: str = ""
+    tool_name: str = ""
+    display: str = ""
+    future: asyncio.Future[ApprovalResponse] | None = None
+
+
+# =================================================================================================
+# Compaction Events
+# =================================================================================================
+
+
+@dataclass
+class CompactionStartEvent:
+    type: Literal["compaction_start"] = "compaction_start"
+
+
+@dataclass
+class CompactionEndEvent:
+    type: Literal["compaction_end"] = "compaction_end"
+    tokens_before: int = 0
+    aborted: bool = False
+    reason: str = ""  # why compaction aborted, empty on success
+
+
+# =================================================================================================
+# Other Events
+# =================================================================================================
+
+
+@dataclass
+class RetryEvent:
+    type: Literal["retry"] = "retry"
+    attempt: int = 0
+    total_attempts: int = 3
+    delay: float = 0.0
+    error: str = ""
+
+
+@dataclass
+class ErrorEvent:
+    type: Literal["error"] = "error"
+    error: str = ""
+
+
+@dataclass
+class WarningEvent:
+    type: Literal["warning"] = "warning"
+    warning: str = ""
+
+
+@dataclass
+class InterruptedEvent:
+    type: Literal["interrupted"] = "interrupted"
+    message: str = "Interrupted by user"
+
+
+# =================================================================================================
+# Union Types
+# =================================================================================================
+
+# Events yielded by run_single_turn (turn.py)
+StreamEvent = (
+    ThinkingStartEvent
+    | ThinkingDeltaEvent
+    | ThinkingEndEvent
+    | TextStartEvent
+    | TextDeltaEvent
+    | TextEndEvent
+    | ToolStartEvent
+    | ToolArgsDeltaEvent
+    | ToolArgsTokenUpdateEvent
+    | ToolEndEvent
+    | ToolResultEvent
+    | ToolApprovalEvent
+    | RetryEvent
+    | TurnEndEvent
+    | ErrorEvent
+    | WarningEvent
+    | InterruptedEvent
+)
+
+# All events yielded by Agent.run() (loop.py)
+Event = (
+    AgentStartEvent
+    | AgentEndEvent
+    | TurnStartEvent
+    | CompactionStartEvent
+    | CompactionEndEvent
+    | StreamEvent
+)

vtx/gh_cli.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from dataclasses import dataclass
+
+from vtx import AVAILABLE_BINARIES
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    number: int
+    branch: str
+    title: str
+
+    def chat_reference(self) -> str:
+        description = _single_line_description(self.title)
+        return f'PR#{self.number} {self.branch} "{description}"'
+
+
+def _single_line_description(description: str) -> str:
+    lines = description.splitlines()
+    first_line = lines[0].strip() if lines else ""
+    hidden_count = len(lines) - 1
+    if hidden_count <= 0:
+        return first_line
+    return f"{first_line} ... ({hidden_count} lines hidden)"
+
+
+_CACHE_TTL_SECONDS = 30.0
+_cached_cwd: str | None = None
+_cached_at: float = 0.0
+_cached_prs: list[PullRequest] = []
+
+
+def is_available() -> bool:
+    return "gh" in AVAILABLE_BINARIES
+
+
+def list_pull_requests(cwd: str = ".") -> list[PullRequest]:
+    global _cached_at, _cached_cwd, _cached_prs
+
+    if not is_available():
+        return []
+
+    now = time.monotonic()
+    if _cached_cwd == cwd and now - _cached_at < _CACHE_TTL_SECONDS:
+        return _cached_prs
+
+    try:
+        result = subprocess.run(
+            ["gh", "pr", "list", "--json", "number,headRefName,title", "--limit", "50"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=2.0,
+        )
+    except Exception:
+        return []
+
+    if result.returncode != 0:
+        return []
+
+    try:
+        raw_prs = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return []
+
+    prs = [
+        PullRequest(
+            number=int(pr["number"]),
+            branch=str(pr.get("headRefName") or ""),
+            title=str(pr.get("title") or ""),
+        )
+        for pr in raw_prs
+        if "number" in pr
+    ]
+    _cached_cwd = cwd
+    _cached_at = now
+    _cached_prs = prs
+    return prs

vtx/git_branch.py

@@ -0,0 +1,90 @@
+import os
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class GitPaths:
+    repo_dir: str
+    common_git_dir: str
+    head_path: str
+
+
+def find_git_paths(cwd: str) -> GitPaths | None:
+    """Find git metadata paths for regular repos and worktrees."""
+    directory = os.path.abspath(cwd)
+    while True:
+        git_path = os.path.join(directory, ".git")
+        if os.path.exists(git_path):
+            try:
+                if os.path.isfile(git_path):
+                    with open(git_path, encoding="utf-8") as f:
+                        content = f.read().strip()
+                    if content.startswith("gitdir: "):
+                        git_dir = os.path.abspath(
+                            os.path.join(directory, content.removeprefix("gitdir: ").strip())
+                        )
+                        head_path = os.path.join(git_dir, "HEAD")
+                        if not os.path.exists(head_path):
+                            return None
+                        common_dir_path = os.path.join(git_dir, "commondir")
+                        if os.path.exists(common_dir_path):
+                            with open(common_dir_path, encoding="utf-8") as f:
+                                common_dir = f.read().strip()
+                            common_git_dir = os.path.abspath(os.path.join(git_dir, common_dir))
+                        else:
+                            common_git_dir = git_dir
+                        return GitPaths(directory, common_git_dir, head_path)
+                elif os.path.isdir(git_path):
+                    head_path = os.path.join(git_path, "HEAD")
+                    if not os.path.exists(head_path):
+                        return None
+                    return GitPaths(directory, git_path, head_path)
+            except OSError:
+                return None
+
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            return None
+        directory = parent
+
+
+def _resolve_branch_with_git(repo_dir: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "--no-optional-locks", "symbolic-ref", "--quiet", "--short", "HEAD"],
+            cwd=repo_dir,
+            capture_output=True,
+            text=True,
+            timeout=1,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+
+    if result.returncode != 0:
+        return None
+    branch = result.stdout.strip()
+    return branch or None
+
+
+def resolve_git_branch(cwd: str) -> str:
+    """Resolve current git branch, returning an empty string outside git repos."""
+    git_paths = find_git_paths(cwd)
+    if git_paths is None:
+        return ""
+
+    try:
+        with open(git_paths.head_path, encoding="utf-8") as f:
+            content = f.read().strip()
+    except OSError:
+        return ""
+
+    prefix = "ref: refs/heads/"
+    if content.startswith(prefix):
+        branch = content.removeprefix(prefix)
+        if branch == ".invalid":
+            return _resolve_branch_with_git(git_paths.repo_dir) or "detached"
+        return branch
+
+    return "detached"

vtx/headless.py

@@ -0,0 +1,127 @@
+import os
+import sys
+from collections.abc import AsyncIterator
+from typing import TextIO
+
+from vtx import config, get_config
+from vtx.config import get_last_selected
+
+from .core.types import StopReason, TextContent
+from .events import AgentEndEvent, ErrorEvent, Event, ToolApprovalEvent, TurnEndEvent
+from .llm.base import AuthMode
+from .permissions import ApprovalResponse
+from .runtime import ConversationRuntime
+from .tools import DEFAULT_TOOLS, get_tools
+
+_EXIT_CODES = {StopReason.STOP: 0, StopReason.ERROR: 1, StopReason.LENGTH: 3}
+
+
+def _exit_code(stop: StopReason) -> int:
+    return _EXIT_CODES.get(stop, 1)
+
+
+def resolve_prompt(prompt_arg: str, *, stdin: TextIO) -> str:
+    if prompt_arg == "-":
+        return stdin.read().strip()
+    return prompt_arg.strip()
+
+
+async def render_run(
+    events: AsyncIterator[Event], *, out: TextIO | None = None, err: TextIO | None = None
+) -> StopReason:
+    out = sys.stdout if out is None else out
+    err = sys.stderr if err is None else err
+    final_text = ""
+    stop = StopReason.ERROR
+    async for event in events:
+        match event:
+            case TurnEndEvent(assistant_message=msg) if msg is not None:
+                text = "".join(p.text for p in msg.content if isinstance(p, TextContent)).strip()
+                if text:
+                    final_text = text
+            case AgentEndEvent(stop_reason=stop_reason):
+                stop = stop_reason
+            case ErrorEvent(error=error):
+                print(f"error: {error}", file=err)
+            case ToolApprovalEvent(tool_name=tool_name, future=future) if future is not None:
+                future.set_result(ApprovalResponse.DENY)
+                print(
+                    f"error: {tool_name!r} requires approval, denied (non-interactive mode)",
+                    file=err,
+                )
+            case _:
+                pass
+    if stop == StopReason.STOP and final_text:
+        print(final_text, file=out)
+    return stop
+
+
+async def run_headless(
+    *,
+    prompt_arg: str,
+    model: str | None,
+    provider: str | None,
+    api_key: str | None,
+    base_url: str | None,
+    openai_compat_auth_mode: AuthMode | None,
+    anthropic_compat_auth_mode: AuthMode | None,
+) -> int:
+    prompt = resolve_prompt(prompt_arg, stdin=sys.stdin)
+    if not prompt:
+        print("error: empty prompt", file=sys.stderr)
+        return 2
+
+    cfg = get_config()
+    previous_permission_mode = cfg.permissions.mode
+    # Headless can't show approval prompts; force auto in-memory for this run only.
+    cfg.permissions.mode = "auto"
+
+    try:
+        last_selected = get_last_selected()
+        initial_model = model or last_selected.model_id or config.llm.default_model
+        initial_provider = (
+            provider
+            if provider is not None
+            else (
+                last_selected.provider
+                if last_selected.model_id
+                else (config.llm.default_provider if model is None else None)
+            )
+        )
+        base = base_url or config.llm.default_base_url or None
+        thinking = last_selected.thinking_level or config.llm.default_thinking_level
+        openai_auth = openai_compat_auth_mode or config.llm.auth.openai_compat
+        anthropic_auth = anthropic_compat_auth_mode or config.llm.auth.anthropic_compat
+
+        tools = get_tools(DEFAULT_TOOLS)
+
+        runtime = ConversationRuntime(
+            cwd=os.getcwd(),
+            model=initial_model,
+            model_provider=initial_provider,
+            api_key=api_key,
+            base_url=base,
+            thinking_level=thinking,
+            tools=tools,
+            openai_compat_auth_mode=openai_auth,
+            anthropic_compat_auth_mode=anthropic_auth,
+        )
+
+        try:
+            init = runtime.initialize()
+            if init.provider_error:
+                print(f"error: {init.provider_error}", file=sys.stderr)
+                return 2
+
+            agent = runtime.prepare_for_run()
+        except Exception as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+
+        if agent is None:
+            print("error: agent initialization failed", file=sys.stderr)
+            return 2
+
+        return _exit_code(await render_run(agent.run(prompt)))
+    finally:
+        cfg.permissions.mode = previous_permission_mode

vtx/llm/__init__.py

@@ -0,0 +1,93 @@
+from .base import DEFAULT_THINKING_LEVELS, BaseProvider, LLMStream, ProviderConfig
+from .dynamic_models import (
+    DYNAMIC_PROVIDERS,
+    DynamicModelEntry,
+    DynamicProviderConfig,
+    find_dynamic_model,
+    get_all_models_with_dynamic,
+    get_dynamic_models,
+    get_dynamic_provider,
+    get_dynamic_provider_headers,
+    get_provider_models,
+    refresh_all_providers,
+    refresh_provider,
+    register_dynamic_provider,
+)
+from .models import (
+    ApiType,
+    Model,
+    get_all_models,
+    get_max_tokens,
+    get_model,
+    get_models_by_provider,
+)
+from .oauth import (
+    clear_api_key,
+    clear_openai_credentials,
+    get_dynamic_api_key,
+    get_provider_status,
+    get_valid_openai_credentials,
+    has_api_key,
+    is_copilot_logged_in,
+    is_openai_logged_in,
+    load_api_key,
+    load_openai_credentials,
+    openai_login,
+    save_api_key,
+)
+from .oauth import clear_credentials as clear_copilot_credentials
+from .oauth import get_valid_token as get_copilot_token
+from .oauth import load_credentials as load_copilot_credentials
+from .oauth import login as copilot_login
+from .provider_catalog import ProviderInfo, detect_provider_from_env, list_providers
+from .provider_catalog import get as get_provider_info
+from .providers import PROVIDER_API_BY_NAME, get_provider_class, resolve_provider_api_type
+
+__all__ = [
+    "DEFAULT_THINKING_LEVELS",
+    "DYNAMIC_PROVIDERS",
+    "PROVIDER_API_BY_NAME",
+    "ApiType",
+    "BaseProvider",
+    "DynamicModelEntry",
+    "DynamicProviderConfig",
+    "LLMStream",
+    "Model",
+    "ProviderConfig",
+    "ProviderInfo",
+    "clear_api_key",
+    "clear_copilot_credentials",
+    "clear_openai_credentials",
+    "copilot_login",
+    "detect_provider_from_env",
+    "find_dynamic_model",
+    "get_all_models",
+    "get_all_models_with_dynamic",
+    "get_copilot_token",
+    "get_dynamic_api_key",
+    "get_dynamic_models",
+    "get_dynamic_provider",
+    "get_dynamic_provider_headers",
+    "get_max_tokens",
+    "get_model",
+    "get_models_by_provider",
+    "get_openai_token",
+    "get_provider_class",
+    "get_provider_info",
+    "get_provider_models",
+    "get_provider_status",
+    "get_valid_openai_credentials",
+    "has_api_key",
+    "is_copilot_logged_in",
+    "is_openai_logged_in",
+    "list_providers",
+    "load_api_key",
+    "load_copilot_credentials",
+    "load_openai_credentials",
+    "openai_login",
+    "refresh_all_providers",
+    "refresh_provider",
+    "register_dynamic_provider",
+    "resolve_provider_api_type",
+    "save_api_key",
+]