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

vtx/__init__.py

@@ -0,0 +1,63 @@
+from vtx.config import (
+    AVAILABLE_BINARIES,
+    CONFIG_DIR_NAME,
+    Config,
+    consume_config_warnings,
+    get_agents_dir,
+    get_config,
+    get_config_dir,
+    reload_config,
+    reset_config,
+    set_colored_tool_badge,
+    set_config,
+    set_git_context,
+    set_notifications_enabled,
+    set_permissions_mode,
+    set_show_welcome_shortcuts,
+    set_theme,
+    set_thinking_lines,
+    update_available_binaries,
+)
+from vtx.context._xml import escape_xml
+from vtx.core.scratchpad import get_scratchpad_dir, init_scratchpad, is_scratchpad_path
+
+
+class _ConfigProxy(Config):
+    """Proxy that delegates to get_config() for runtime reloading and test injection."""
+
+    def __init__(self) -> None:
+        # Do not call super().__init__(): all attribute access is delegated to
+        # the live config returned by get_config() via __getattr__ below.
+        pass
+
+    def __getattr__(self, name: str):
+        return getattr(get_config(), name)
+
+
+config = _ConfigProxy()
+
+__all__ = [
+    "AVAILABLE_BINARIES",
+    "CONFIG_DIR_NAME",
+    "Config",
+    "config",
+    "consume_config_warnings",
+    "escape_xml",
+    "get_agents_dir",
+    "get_config",
+    "get_config_dir",
+    "get_scratchpad_dir",
+    "init_scratchpad",
+    "is_scratchpad_path",
+    "reload_config",
+    "reset_config",
+    "set_colored_tool_badge",
+    "set_config",
+    "set_git_context",
+    "set_notifications_enabled",
+    "set_permissions_mode",
+    "set_show_welcome_shortcuts",
+    "set_theme",
+    "set_thinking_lines",
+    "update_available_binaries",
+]

vtx/async_utils.py

@@ -0,0 +1,40 @@
+import asyncio
+from contextlib import suppress
+from typing import Any
+
+
+class OperationCancelledError(Exception):
+    pass
+
+
+async def cancel_and_await(task: asyncio.Future[Any]) -> None:
+    if task.done():
+        return
+    task.cancel()
+    with suppress(asyncio.CancelledError):
+        await task
+
+
+async def await_or_cancel[T](work: asyncio.Future[T], cancel_event: asyncio.Event | None) -> T:
+    if not cancel_event:
+        return await work
+
+    if cancel_event.is_set():
+        await cancel_and_await(work)
+        raise OperationCancelledError
+
+    cancel = asyncio.create_task(cancel_event.wait())
+    try:
+        done, pending = await asyncio.wait({work, cancel}, return_when=asyncio.FIRST_COMPLETED)
+
+        for task in pending:
+            await cancel_and_await(task)
+
+        if cancel in done and cancel_event.is_set():
+            if not work.done():
+                await cancel_and_await(work)
+            raise OperationCancelledError
+
+        return work.result()
+    finally:
+        await cancel_and_await(cancel)

vtx/builtin_skills/github/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: github
+description: Run GitHub CLI commands, manage repositories, issues, PRs, releases, actions, or call arbitrary REST/GraphQL endpoints using `gh api`
+register_cmd: true
+---
+
+# GitHub CLI & API Skill
+
+Use this skill when you need to interact with GitHub repositories, pull requests, issues, releases, actions, or configure GitHub settings. This skill relies on the GitHub CLI (`gh`) and the GitHub REST/GraphQL APIs.
+
+---
+
+## 🔐 Authentication & Setup
+
+Before running commands, verify your login status and configure authentication if needed.
+
+### Check login status
+```bash
+gh auth status
+```
+
+### Authenticate
+If not authenticated, or if you need a token in a script:
+- **Interactive login:** `gh auth login`
+- **Non-interactive token login:**
+  ```bash
+  echo "YOUR_GITHUB_TOKEN" | gh auth login --with-token
+  ```
+- **Environment variable:** Expose `GITHUB_TOKEN` in your environment. Many tools and commands automatically read `GITHUB_TOKEN`.
+
+---
+
+## 🛠️ GitHub CLI Command Reference
+
+Below are the most common GitHub CLI operations. Always prefer using built-in `gh` subcommands over direct `gh api` queries for standard actions.
+
+### 📦 Repository Management
+* **List Repositories:** `gh repo list [owner] --limit 50`
+* **Create Repository:** `gh repo create [name] --public --clone`
+* **Fork Repository:** `gh repo fork --clone`
+* **Clone Repository:** `gh repo clone OWNER/REPO`
+* **View Repo Info:** `gh repo view --web`
+
+### 🔧 Issues
+* **List Issues:** `gh issue list --state open --assignee @me`
+* **Create Issue:** `gh issue create --title "Title" --body "Body content" --label "bug,help-wanted"`
+* **View/Comment Issue:**
+  * View issue: `gh issue view 123`
+  * Comment on issue: `gh issue comment 123 --body "Nice fix!"`
+* **Close/Reopen Issue:**
+  * Close issue: `gh issue close 123 --reason "completed"`
+  * Reopen issue: `gh issue reopen 123`
+
+### 🔀 Pull Requests
+* **List PRs:** `gh pr list --state open --limit 20`
+* **Create PR:** `gh pr create --title "Title" --body "Body description" --base main --head feature-branch`
+* **Checkout PR:** `gh pr checkout 123`
+* **Review PR:** `gh pr review 123 --approve --body "Looks good to go!"`
+* **Merge PR:** `gh pr merge 123 --merge --delete-branch`
+* **Check Status:** `gh pr checks 123`
+* **View Diff:** `gh pr diff 123`
+
+### 🚀 Releases
+* **List Releases:** `gh release list`
+* **Create Release:** `gh release create v1.0.0 --title "v1.0.0" --notes "Release notes text"`
+* **Upload Assets:** `gh release create v1.0.0 ./dist/bundle.tar.gz ./dist/metadata.json`
+
+### ⚙️ Secrets & Environments
+* **List Secrets:** `gh secret list`
+* **Set Repository Secret:** `gh secret set MY_SECRET --body "secret_value"`
+* **Set Environment Secret:** `gh secret set MY_SECRET --env production --body "secret_value"`
+
+### 🔄 GitHub Actions & Workflows
+* **List Workflows:** `gh workflow list`
+* **List Runs:** `gh run list --workflow=ci.yml --limit 5`
+* **View Run Logs:** `gh run view 123456 --log`
+* **Trigger Workflow:** `gh workflow run ci.yml -f ref=main -f environment=staging`
+
+---
+
+## 📡 Advanced GitHub API Integration (`gh api`)
+
+When built-in `gh` commands do not support the operation, use `gh api` to talk directly to GitHub's REST or GraphQL endpoints.
+
+### Key Features of `gh api`
+1. **Automatic Placeholders:** The API command automatically expands `{owner}` and `{repo}` with the details of your current repository directory (e.g. `repos/{owner}/{repo}/issues` maps to `repos/OEvortex/vtx-coding-agent/issues`).
+2. **Method Detection:** Defaults to `GET`. Automatically switches to `POST` if request parameters (`-f`/`-F`) are passed. You can override with `--method DELETE` or `--method PUT`.
+3. **Type Binding:**
+   * `-f / --raw-field` maps parameters as raw strings.
+   * `-F / --field` parses fields to their JSON representations (numbers, booleans, arrays). To load content from a file, prefix the value with `@` (e.g., `-F body=@issue_template.md`).
+
+### Common `gh api` Examples
+
+#### 1. Retrieve current user details
+```bash
+gh api user
+```
+
+#### 2. Create a comment on an issue/PR (REST)
+```bash
+gh api repos/{owner}/{repo}/issues/123/comments -f body="Automated comment via API"
+```
+
+#### 3. List workflow runs in a repository
+```bash
+gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[] | {id, status, conclusion}'
+```
+
+#### 4. Run a GraphQL Query
+```bash
+gh api graphql -f query='
+  query {
+    viewer {
+      login
+      createdAt
+    }
+  }
+'
+```
+
+#### 5. Fetch a file content via API
+```bash
+gh api repos/{owner}/{repo}/contents/path/to/file.py --jq '.content' | base64 --decode
+```
+
+---
+
+## 💡 Best Practices
+
+1. **Disable Interactive Prompts:** By default, commands like `gh pr create` or `gh repo create` can prompt for inputs interactively. In scripts or unattended environments, always add the non-interactive flags (e.g., `-y`, `--confirm`, or provide all arguments such as `--title` and `--body` explicitly).
+2. **Filter Output with `jq`:** GitHub API responses are large JSON structures. Use the CLI's built-in `--jq` flag or pipe to external `jq` for readability.
+   ```bash
+   gh issue list --json number,title --jq '.[] | "#\(.number) \(.title)"'
+   ```
+3. **Environment Variables for Context:** If you need to target a repository outside the current git working directory, set the `GH_REPO` variable:
+   ```bash
+   GH_REPO="other-owner/other-repo" gh issue list
+   ```
+4. **Rate Limit Handling:** Use `gh api rate_limit` to check your current REST/GraphQL API rate limits if executing a loop or batch task.

vtx/builtin_skills/init/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: init
+description: Create or update AGENTS.md for this repository
+register_cmd: true
+cmd_info: guided AGENTS.md setup
+category: setup
+---
+
+Create or update `AGENTS.md` for this repository.
+
+The goal is a compact instruction file that helps future Vtx sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## How to investigate
+
+Read the highest-value sources first:
+- `README*`, root manifests, workspace config, lockfiles
+- build, test, lint, formatter, typecheck, and codegen config
+- CI workflows and pre-commit / task runner config
+- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- repo-local Vtx config and conventions
+
+If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
+
+Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
+
+## What to extract
+
+Look for the highest-signal facts for an agent working in this repo:
+- exact developer commands, especially non-obvious ones
+- how to run a single test, a single package, or a focused verification step
+- required command order when it matters, such as `lint -> typecheck -> test`
+- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
+- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
+- repo-specific style or workflow conventions that differ from defaults
+- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
+- important constraints from existing instruction files worth preserving
+
+Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.
+
+## Questions
+
+Only ask the user questions if the repo cannot answer something important. Use the question tool for one short batch at most.
+
+Good questions:
+- undocumented team conventions
+- branch / PR / release expectations
+- missing setup or test prerequisites that are known but not written down
+
+Do not ask about anything the repo already makes clear.
+
+## Writing rules
+
+Include only high-signal, repo-specific guidance such as:
+- exact commands and shortcuts the agent would otherwise guess wrong
+- architecture notes that are not obvious from filenames
+- conventions that differ from language or framework defaults
+- setup requirements, environment quirks, and operational gotchas
+- references to existing instruction sources that matter
+
+Exclude:
+- generic software advice
+- long tutorials or exhaustive file trees
+- obvious language conventions
+- speculative claims or anything you could not verify
+- content better stored in another file referenced via Vtx config or another instruction file
+
+When in doubt, omit.
+
+Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
+
+If `AGENTS.md` already exists, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.

vtx/builtin_skills/review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: review
+description: Review code changes and return prioritized, actionable findings
+register_cmd: true
+cmd_info: review code changes
+category: review
+---
+
+Review the requested code changes as if you are reviewing another engineer's PR.
+
+User-provided target or constraints (honor these):
+$ARGUMENTS
+
+## Target selection
+
+- If no target is provided, review the current code changes: staged, unstaged, and untracked files.
+- If the user provides a base branch, review the changes that would merge into that branch. Find the merge base and inspect the diff from that commit.
+- If the user provides a commit SHA, review only the changes introduced by that commit.
+- If the user provides a PR number, PR URL, or text like `PR#68 feat/headless-mode "feat: add non-interactive prompt mode"`, assume the GitHub CLI is available. Use `gh pr view` to inspect PR metadata, resolve the base/head branches, fetch as needed, compute the merge base, and review the PR diff. Do not checkout a different branch unless the user explicitly asks or confirms.
+- For PRs, do not assume the head branch exists on `origin`; it may live on a contributor fork. Prefer `gh pr checkout --detach <number>` only if checkout is acceptable, or fetch the head repository/ref reported by `gh pr view --json headRepository,headRefName` into a temporary remote/ref before diffing.
+- For a PR scenario such as `/review PR#68 feat/headless-mode "feat: add non-interactive prompt mode"`, use the PR number/title/branch as hints, verify them with `gh pr view 68`, then review the code changes relative to the PR base branch.
+
+## Review rubric
+
+Only report issues the original author would likely fix if they knew about them.
+
+Flag a finding only when:
+- it meaningfully affects correctness, security, performance, reliability, or maintainability;
+- it is discrete and actionable;
+- it appears introduced by the reviewed change;
+- you can identify the affected code path or user scenario;
+- it is not merely a style preference, nit, or intentional behavior change.
+
+Do not stop at the first issue. Return all qualifying findings. If there are no findings worth fixing, say so clearly.
+
+## Investigation guidance
+
+Use repository tools to inspect the actual diff and surrounding code. Prefer precise commands such as:
+- `git status --short`
+- `git diff --staged`
+- `git diff`
+- `git diff <merge-base>...HEAD`
+- `git show <sha>`
+- `gh pr view <number> --json number,title,body,baseRefName,headRefName,url,author`
+
+Read nearby implementation and tests when needed to prove whether a suspected issue is real. Avoid speculative findings.
+
+## Priority rubric
+
+Use these severity levels for finding titles:
+- `[P0]` — Drop everything to fix. Blocking release, operations, or major usage. Only use for universal issues that do not depend on assumptions about inputs.
+- `[P1]` — Urgent. Should be addressed in the next cycle.
+- `[P2]` — Normal. Should be fixed eventually.
+- `[P3]` — Low. Nice to have.
+
+## Finding format
+
+For each finding, include:
+- priority tag in the title: `[P0]`, `[P1]`, `[P2]`, or `[P3]`;
+- concise title;
+- file path and line range;
+- one short paragraph explaining why this is a bug and when it matters;
+- confidence score if useful.
+
+Keep line ranges as short as possible and make sure they overlap the reviewed diff when possible.
+
+End with an overall verdict:
+- `patch is correct` if existing code/tests should not break and no blocking issues were found;
+- `patch is incorrect` if the patch has blocking correctness, security, reliability, or maintainability issues that should prevent merging.
+
+Do not mark a patch incorrect for non-blocking issues such as style, formatting, typos, documentation nits, or ordinary `[P2]`/`[P3]` follow-ups unless they still indicate the patch should not merge.
+
+Do not fix the code unless the user asks after the review.

vtx/builtin_skills/skill-builder/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: skill-builder
+description: Create a new Vtx skill (SKILL.md) with the correct frontmatter, body, and conventions
+register_cmd: true
+cmd_info: scaffold a new skill
+category: meta
+---
+
+Create a new Vtx skill at the right location with the right shape.
+
+A skill is a directory containing a `SKILL.md`. Vtx auto-discovers skills from `<cwd-or-ancestor>/.agents/skills/` (project) and `~/.agents/skills/` (user). Project skills shadow user skills with the same name. The skill name MUST match the directory name.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## Where to put it
+
+- Project skill (preferred for repo-specific workflows): `<repo>/.agents/skills/<name>/SKILL.md`. Use this when the skill encodes conventions, commands, or escape hatches that only make sense in this repo.
+- User skill (preferred for personal workflows): `~/.agents/skills/<name>/SKILL.md`. Use this for cross-repo utilities (e.g. "release-checklist", "draft-pr").
+- Never put a skill at the repo root or in a non-`.agents/skills/` path — Vtx will not discover it.
+
+## Frontmatter (YAML between `---` markers)
+
+Required:
+- `name` — lowercase letters, digits, hyphens. Must equal the directory name. Max 64 chars. No leading/trailing hyphen, no `--`.
+
+Recommended:
+- `description` — required (the loader rejects skills without one). One short sentence, max 1024 chars. Describe the trigger, not the implementation. The agent uses this to decide when to load the skill.
+- `category` — one of `setup`, `review`, `workflows`, `meta`, `general`, etc. Categories group skills in the `<available_skills>` index. Default is `general` if omitted. Max 32 chars.
+- `register_cmd: true` — expose the skill as a slash command (`/<name>`) and include it in the `/` menu. Add this when the skill is something the user would invoke explicitly.
+- `register_cmd: only` — register the slash command but do NOT inject the skill into the system prompt. Use for heavy skills that should be loaded on demand only.
+- `cmd_info` — short label shown in the slash menu (max 32 chars). Required when `register_cmd` is true.
+
+Minimal valid frontmatter:
+
+```yaml
+---
+name: my-skill
+description: Do the X thing when the user asks for X
+---
+```
+
+Full frontmatter:
+
+```yaml
+---
+name: my-skill
+description: Do the X thing when the user asks for X
+register_cmd: true
+cmd_info: run the X thing
+category: workflows
+---
+```
+
+## Body
+
+The body is plain Markdown, shown verbatim when the skill loads. Treat it as instructions to a future agent.
+
+Conventions:
+- Open with a one-line summary of what the skill does.
+- Include `User-provided focus or constraints (honor these):` followed by `$ARGUMENTS` so the slash-command arguments are passed through.
+- Use `##` and `###` sections. Vtx renders them as headings; the agent uses them to skim.
+- Prefer concrete commands, file paths, and decision rules over prose.
+- Keep it focused. A skill that tries to cover everything is worse than several focused skills. Move long reference material to a separate file in the skill directory and link to it.
+
+## Validating
+
+After writing, sanity-check:
+1. `name` matches the directory name.
+2. Description is non-empty, one sentence, names the trigger condition.
+3. If `register_cmd: true` is set, `cmd_info` is set and under 32 chars.
+4. Category (if set) is short and reusable across skills.
+5. No required frontmatter field is missing.
+
+Vtx logs warnings to stderr on load for invalid skills. Restart Vtx or run `/new` to reload the index after creating a new skill.
+
+## What to write vs. what to skip
+
+Write:
+- exact commands the agent would otherwise guess wrong
+- repo or workflow-specific decision rules
+- escape hatches for known gotchas
+- the user-provided arguments passthrough line (`$ARGUMENTS`)
+
+Skip:
+- generic coding advice (the base system prompt already covers it)
+- long tutorials that belong in README or docs
+- speculative or unverifiable claims
+- duplicated content that is already in `AGENTS.md` (reference it instead)
+
+## Example
+
+For a skill that drafts release notes from the recent git log:
+
+Path: `~/.agents/skills/draft-release-notes/SKILL.md`
+
+```markdown
+---
+name: draft-release-notes
+description: Draft release notes from `git log` between the last tag and HEAD
+register_cmd: true
+cmd_info: draft release notes
+category: workflows
+---
+
+Draft release notes for the next release.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## Steps
+
+1. Find the last release tag: `git describe --tags --abbrev=0`.
+2. Collect commits since that tag: `git log <tag>..HEAD --oneline --no-merges`.
+3. Group by area (use the conventional-commit prefix or the directories touched).
+4. Write a short bullet list under `## Highlights` and `## Fixes`, mirroring the user's requested tone.
+5. Print the result; do not write to a file unless the user asked.
+
+## Style
+
+- One bullet per change. Lead with the user-facing effect, not the implementation.
+- Group by area, not by commit order.
+- Skip dependency bumps and pure refactors unless they affect behavior.
+```
+
+## Common mistakes to avoid
+
+- Setting `description` to a list of features instead of a trigger condition. The agent reads the description to decide whether to load the skill — a vague description means the skill rarely fires.
+- Putting long body content in `description`. Description is a summary, not the body.
+- Forgetting `$ARGUMENTS`. Without it, slash-command arguments are dropped.
+- Naming the skill `foo` but putting it in `.agents/skills/foo-bar/`. The loader warns and may not surface the skill.
+- Setting `register_cmd: true` without `cmd_info`. The slash menu will show an empty entry.
+- Writing a skill that duplicates an existing one. Run `/` and check the menu first; if a similar skill exists, extend it or add a category to disambiguate.

vtx/cli.py

@@ -0,0 +1,90 @@
+import argparse
+import asyncio
+
+from vtx import config
+
+from .llm import PROVIDER_API_BY_NAME
+from .version import VERSION
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Vtx")
+    parser.add_argument("--model", "-m", help="Model to use")
+    parser.add_argument("--provider", choices=sorted(PROVIDER_API_BY_NAME), help="Provider to use")
+    parser.add_argument(
+        "--prompt",
+        "-p",
+        nargs="?",
+        const="-",
+        default=None,
+        help="Run a single prompt non-interactively, then exit "
+        "(omit the value or pipe stdin to read the prompt from stdin)",
+    )
+    parser.add_argument("--api-key", "-k", help="API key")
+    parser.add_argument("--base-url", "-u", help="Base URL for API")
+    parser.add_argument(
+        "--openai-compat-auth",
+        choices=("auto", "required", "none"),
+        help="Auth mode for OpenAI-compatible endpoints",
+    )
+    parser.add_argument(
+        "--anthropic-compat-auth",
+        choices=("auto", "required", "none"),
+        help="Auth mode for Anthropic-compatible endpoints",
+    )
+    parser.add_argument(
+        "--insecure-skip-verify",
+        action="store_true",
+        help="Skip TLS verification (e.g. self-signed certs on local providers)",
+    )
+    parser.add_argument(
+        "--continue",
+        "-c",
+        action="store_true",
+        dest="continue_recent",
+        help="Resume the most recent session",
+    )
+    parser.add_argument(
+        "--resume",
+        "-r",
+        dest="resume_session",
+        help="Resume a specific session by ID (full or unique prefix)",
+    )
+    parser.add_argument("--version", action="version", version=f"vtx {VERSION}")
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.prompt is not None and (args.continue_recent or args.resume_session):
+        parser.error("-c/--continue and -r/--resume are not supported with -p/--prompt")
+
+    if args.insecure_skip_verify:
+        config.llm.tls.insecure_skip_verify = True
+
+    if args.prompt is not None:
+        from .headless import run_headless
+
+        raise SystemExit(
+            asyncio.run(
+                run_headless(
+                    prompt_arg=args.prompt,
+                    model=args.model,
+                    provider=args.provider,
+                    api_key=args.api_key,
+                    base_url=args.base_url,
+                    openai_compat_auth_mode=args.openai_compat_auth,
+                    anthropic_compat_auth_mode=args.anthropic_compat_auth,
+                )
+            )
+        )
+
+    from .ui.launch import run_tui
+
+    run_tui(args)
+
+
+if __name__ == "__main__":
+    main()