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

vtx/core/__init__.py

@@ -0,0 +1,47 @@
+from .errors import format_error
+from .scratchpad import get_scratchpad_dir, init_scratchpad, is_scratchpad_path
+from .types import (
+    AssistantMessage,
+    ImageContent,
+    Message,
+    StopReason,
+    StreamDone,
+    StreamError,
+    StreamPart,
+    TextContent,
+    TextPart,
+    ThinkingContent,
+    ThinkPart,
+    ToolCall,
+    ToolCallDelta,
+    ToolCallStart,
+    ToolDefinition,
+    ToolResultMessage,
+    Usage,
+    UserMessage,
+)
+
+__all__ = [
+    "AssistantMessage",
+    "ImageContent",
+    "Message",
+    "StopReason",
+    "StreamDone",
+    "StreamError",
+    "StreamPart",
+    "TextContent",
+    "TextPart",
+    "ThinkPart",
+    "ThinkingContent",
+    "ToolCall",
+    "ToolCallDelta",
+    "ToolCallStart",
+    "ToolDefinition",
+    "ToolResultMessage",
+    "Usage",
+    "UserMessage",
+    "format_error",
+    "get_scratchpad_dir",
+    "init_scratchpad",
+    "is_scratchpad_path",
+]

vtx/core/compaction.py

@@ -0,0 +1,89 @@
+"""
+Context compaction for long sessions.
+
+When token usage exceeds the usable context window, send the full conversation
+to the LLM with a summarization prompt, then store the summary as a
+CompactionEntry. The session.messages property filters to only show messages
+after the compaction point.
+
+Overflow formula:
+    total_tokens >= context_window - min(buffer_tokens, max_output_tokens)
+"""
+
+from ..core.types import Message, TextPart, Usage, UserMessage
+from ..llm.base import BaseProvider
+
+SUMMARIZATION_PROMPT = """Provide a detailed prompt for continuing our \
+conversation above. Focus on information that would be helpful for \
+continuing the conversation, including what we did, what we're doing, \
+which files we're working on, and what we're going to do next. \
+The summary that you construct will be used so that another agent \
+can read it and continue the work.
+
+When constructing the summary, try to stick to this template:
+---
+## Goal
+
+[What goal(s) is the user trying to accomplish?]
+
+## Instructions
+
+- [What important instructions did the user give you that are relevant]
+- [If there is a plan or spec, include information about it
+  so next agent can continue using it]
+
+## Discoveries
+
+[What notable things were learned during this conversation that would
+be useful for the next agent to know when continuing the work]
+
+## Accomplished
+
+[What work has been completed, what work is still in progress,
+and what work is left?]
+
+## Relevant files / directories
+
+[Construct a structured list of relevant files that have been read,
+edited, or created that pertain to the task at hand. If all the files
+in a directory are relevant, include the path to the directory.]
+---"""
+
+
+def is_overflow(
+    usage: Usage, context_window: int, max_output_tokens: int, buffer_tokens: int
+) -> bool:
+    count = (
+        usage.input_tokens
+        + usage.output_tokens
+        + usage.cache_read_tokens
+        + usage.cache_write_tokens
+    )
+    reserved = min(buffer_tokens, max_output_tokens)
+    usable = context_window - reserved
+    return count >= usable
+
+
+def _calculate_context_tokens(usage: Usage) -> int:
+    return (
+        usage.input_tokens
+        + usage.output_tokens
+        + usage.cache_read_tokens
+        + usage.cache_write_tokens
+    )
+
+
+async def generate_summary(
+    messages: list[Message], provider: BaseProvider, system_prompt: str | None = None
+) -> str:
+    """Send the full conversation + summarization prompt to the LLM, return summary text."""
+    summary_messages: list[Message] = [*messages, UserMessage(content=SUMMARIZATION_PROMPT)]
+
+    stream = await provider.stream(summary_messages, system_prompt=system_prompt, tools=None)
+
+    text_parts: list[str] = []
+    async for part in stream:
+        if isinstance(part, TextPart):
+            text_parts.append(part.text)
+
+    return "".join(text_parts)

vtx/core/errors.py

@@ -0,0 +1,17 @@
+"""Shared error formatting for provider/agent error surfaces.
+
+Errors crossing the event boundary (StreamError, ErrorEvent, compaction
+failures) are reduced to strings, so the exception type must be baked into
+the message or it is lost to the user.
+"""
+
+
+def format_error(error: BaseException) -> str:
+    name = type(error).__name__
+    message = str(error).strip()
+    if not message:
+        return f"{name}: failed without an error message"
+    # Some SDK errors already stringify with their type name; don't repeat it.
+    if message.startswith(name):
+        return message
+    return f"{name}: {message}"

vtx/core/handoff.py

@@ -0,0 +1,51 @@
+from ..core.types import Message, TextPart, UserMessage
+from ..llm.base import BaseProvider
+
+HANDOFF_PROMPT_TEMPLATE = """You are creating a handoff to a NEW focused thread.
+
+New thread goal (from user):
+{query}
+
+Based on the conversation above, write the exact opening user prompt for the new thread.
+
+Requirements:
+- Focus ONLY on context relevant to the new goal.
+- Preserve critical decisions, constraints, and assumptions.
+- Include concrete file paths and why they matter (only if relevant).
+- Include current status: done, in progress, and next action.
+- Do not invent facts; if unknown, say "Unknown".
+- Do not include backlinks, UI notes, or any metadata.
+- Do not mention "handoff", "summary", or "conversation above".
+- Output must be ready to send as-is by the user in the new thread.
+
+Output format (plain text, no markdown code fences):
+Task: <clear goal>
+
+Context to keep:
+- ...
+
+Relevant files:
+- <path> — <why it matters>
+
+Constraints:
+- ...
+
+Next steps:
+1. ...
+2. ..."""
+
+
+async def generate_handoff_prompt(
+    messages: list[Message], provider: BaseProvider, system_prompt: str | None, query: str
+) -> str:
+    handoff_prompt = HANDOFF_PROMPT_TEMPLATE.format(query=query.strip())
+    handoff_messages: list[Message] = [*messages, UserMessage(content=handoff_prompt)]
+
+    stream = await provider.stream(handoff_messages, system_prompt=system_prompt, tools=None)
+
+    text_parts: list[str] = []
+    async for part in stream:
+        if isinstance(part, TextPart):
+            text_parts.append(part.text)
+
+    return "".join(text_parts).strip()

vtx/core/scratchpad.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from vtx import get_config_dir
+
+_active_scratchpads: dict[str, Path] = {}
+
+
+def init_scratchpad(session_id: str) -> Path | None:
+    """Create a session-scoped scratchpad directory under VTX config dir.
+
+    Each session gets its own scratchpad directory. Idempotent per session_id.
+    """
+    if session_id in _active_scratchpads:
+        return _active_scratchpads[session_id]
+
+    try:
+        config_dir = get_config_dir()
+        dir_path = config_dir / "scratchpads" / f"vtx-scratchpad-{session_id[:8]}"
+        dir_path.mkdir(parents=True, exist_ok=True)
+        _active_scratchpads[session_id] = dir_path
+        return dir_path
+    except OSError:
+        return None
+
+
+def get_scratchpad_dir(session_id: str) -> Path | None:
+    """Return the scratchpad directory for a given session, or None."""
+    return _active_scratchpads.get(session_id)
+
+
+def is_scratchpad_path(path_str: str) -> bool:
+    """Return True if the resolved path is inside any active scratchpad.
+
+    Uses Path.resolve() to defeat path traversal and symlink attacks.
+    """
+    if not _active_scratchpads:
+        return False
+    try:
+        resolved = Path(path_str).expanduser().resolve()
+        return any(
+            _is_subpath(resolved, sp_dir.resolve()) for sp_dir in _active_scratchpads.values()
+        )
+    except (ValueError, OSError):
+        return False
+
+
+def _is_subpath(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False

vtx/core/types.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class StopReason(StrEnum):
+    STOP = "stop"
+    LENGTH = "length"
+    TOOL_USE = "tool_use"
+    ERROR = "error"
+    INTERRUPTED = "interrupted"
+    STEER = "steer"
+
+
+class Usage(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+    @property
+    def total_tokens(self) -> int:
+        return (
+            self.input_tokens
+            + self.output_tokens
+            + self.cache_read_tokens
+            + self.cache_write_tokens
+        )
+
+
+# =================================================================================================
+# Stream Parts - yielded by providers during streaming
+# =================================================================================================
+
+
+class TextPart(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+    def merge(self, other: TextPart) -> TextPart:
+        return TextPart(text=self.text + other.text)
+
+
+class ThinkPart(BaseModel):
+    type: Literal["think"] = "think"
+    think: str
+    signature: str | None = None
+
+    def merge(self, other: ThinkPart) -> ThinkPart:
+        signature = self.signature or other.signature
+        return ThinkPart(think=self.think + other.think, signature=signature)
+
+
+class ToolCallStart(BaseModel):
+    type: Literal["tool_call_start"] = "tool_call_start"
+    id: str
+    name: str
+    index: int  # Tool call index for correlating deltas
+    arguments: dict[str, Any] | None = None
+
+
+class ToolCallDelta(BaseModel):
+    type: Literal["tool_call_delta"] = "tool_call_delta"
+    index: int  # Correlates with ToolCallStart.index
+    arguments_delta: str
+    replace: bool = False
+
+
+class StreamDone(BaseModel):
+    type: Literal["done"] = "done"
+    stop_reason: StopReason
+
+
+class StreamError(BaseModel):
+    type: Literal["error"] = "error"
+    error: str
+
+
+StreamPart = TextPart | ThinkPart | ToolCallStart | ToolCallDelta | StreamDone | StreamError
+
+
+# =================================================================================================
+# Message Types - canonical provider-agnostic conversation interface
+# Used for conversation history and cross-provider normalization
+# =================================================================================================
+
+
+class TextContent(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ThinkingContent(BaseModel):
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+    signature: str | None = None
+
+
+class ImageContent(BaseModel):
+    type: Literal["image"] = "image"
+    data: str  # base64 encoded
+    mime_type: str
+
+
+class ToolCall(BaseModel):
+    type: Literal["tool_call"] = "tool_call"
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+class UserMessage(BaseModel):
+    role: Literal["user"] = "user"
+    content: str | list[TextContent | ImageContent]
+
+
+class AssistantMessage(BaseModel):
+    role: Literal["assistant"] = "assistant"
+    content: list[TextContent | ThinkingContent | ToolCall]
+    usage: Usage | None = None
+    stop_reason: StopReason | None = None
+
+
+class ToolResultMessage(BaseModel):
+    role: Literal["tool_result"] = "tool_result"
+    tool_call_id: str
+    tool_name: str
+    content: list[TextContent | ImageContent]
+    ui_summary: str | None = None  # One-line UI text rendered on tool header line
+    ui_details: str | None = None  # Collapsed multiline UI text rendered below the header
+    ui_details_full: str | None = None  # Expanded multiline UI text rendered below the header
+    is_error: bool = False
+    file_changes: FileChanges | None = None
+
+
+Message = UserMessage | AssistantMessage | ToolResultMessage
+
+
+# =================================================================================================
+# Tool Definition
+# =================================================================================================
+
+
+class ToolParameter(BaseModel):
+    type: str
+    description: str | None = None
+    enum: list[str] | None = None
+
+
+class ToolDefinition(BaseModel):
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema
+
+
+class FileChanges(BaseModel):
+    path: str
+    added: int = 0
+    removed: int = 0
+
+
+class ToolResult(BaseModel):
+    success: bool
+    result: str | None = None  # Raw result (sent to LLM)
+    images: list[ImageContent] | None = None  # Images to include in result
+    ui_summary: str | None = None  # One-line result text appended to the tool header
+    ui_details: str | None = None  # Collapsed multiline result body rendered below the header
+    ui_details_full: str | None = None  # Expanded multiline result body rendered below the header
+    file_changes: FileChanges | None = None  # Track +/- lines for edit/write tools
+
+
+# UI rendering model:
+#
+# format_call is defined for each tool like Read tool and the result they
+# return contains further details (along with the resulf for llm) to help paint
+# the coomplete picture (or as close to it as possible without polluting) in the ui
+#
+# - format_call(params): short call text shown on the header line
+# - ui_summary: one-line result summary appended to the same header line
+# - ui_details: multiline result body shown below the header
+#
+# Example (read):
+#   → Read ~/src/vtx/turn.py:150-204 (55 lines)
+#   - format_call -> "~/src/vtx/turn.py:150-204"
+#   - ui_summary  -> "(55 lines)"
+#   - ui_details  -> None
+#
+# Example (edit):
+#   + Edit ~/src/vtx/tools/base.py +3 -1
+#     -12 old line
+#     +12 new line
+#   - format_call -> "~/src/vtx/tools/base.py"
+#   - ui_summary  -> "+3 -1"
+#   - ui_details  -> formatted diff

vtx/defaults/config.yml

@@ -0,0 +1,53 @@
+meta:
+  config_version: 6
+
+llm:
+  default_provider: "openai-codex"
+  default_model: "gpt-5.5"
+  default_base_url: ""
+  default_thinking_level: "low"
+  tool_call_idle_timeout_seconds: 180
+  request_timeout_seconds: 600
+
+  auth:
+    openai_compat: "auto"
+    anthropic_compat: "auto"
+
+  tls:
+    insecure_skip_verify: false
+
+  system_prompt:
+    git_context: true
+    # Base identity + general rules. Defaults to vtx.prompts.identity.DEFAULT_VTX_BASE
+    # (sourced from Python). Set a custom string here to override the base prompt;
+    # extra sections (tool guidelines, AGENTS.md, skills, git, env) are still
+    # appended automatically.
+    content: ""
+
+compaction:
+  on_overflow: "continue"
+  buffer_tokens: 20000
+
+agent:
+  max_turns: 500
+  default_context_window: 200000
+
+ui:
+  theme: "gruvbox-dark"
+  collapse_thinking: true
+  show_welcome_shortcuts: true
+  hidden_models: []
+
+permissions:
+  mode: "prompt"
+
+notifications:
+  enabled: false
+  volume: 0.5
+
+# Example: DeepSeek provider
+# export DEEPSEEK_API_KEY="sk-your-api-key"
+#
+# Then set in [llm]:
+# default_provider = "deepseek"
+# default_model = "deepseek-v4-flash"

vtx/diff_display.py

@@ -0,0 +1,12 @@
+DIFF_BG_PAD_MARKER = "__VTX_DIFF_BG_PAD__"
+
+
+def blend_hex(fg_hex: str, bg_hex: str, alpha: float = 0.15) -> str:
+    fg_hex = fg_hex.lstrip("#")
+    bg_hex = bg_hex.lstrip("#")
+    fr, fg, fb = int(fg_hex[:2], 16), int(fg_hex[2:4], 16), int(fg_hex[4:6], 16)
+    br, bg_c, bb = int(bg_hex[:2], 16), int(bg_hex[2:4], 16), int(bg_hex[4:6], 16)
+    r = int(fr * alpha + br * (1 - alpha))
+    g = int(fg * alpha + bg_c * (1 - alpha))
+    b = int(fb * alpha + bb * (1 - alpha))
+    return f"#{r:02x}{g:02x}{b:02x}"