voidx 1.0.0__tar.gz

voidx-1.0.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: voidx
+Version: 1.0.0
+Summary: A coding agent that quantifies everything and solves with tools, not fuzzy prompts.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: langgraph>=0.3.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langchain-anthropic>=0.3.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
+
+# voidx
+
+voidx is a terminal AI coding agent built in Python.
+
+## Install
+
+Python users can install the canonical package from PyPI:
+
+```bash
+pip install voidx
+voidx
+```
+
+Node users can install the npm launcher. The launcher requires Python 3.11+
+on the machine and installs the matching Python package into an isolated
+user-local virtual environment on first run:
+
+```bash
+npm install -g @voidx/cli
+voidx
+```
+
+## Useful Commands
+
+```bash
+voidx version
+voidx sessions
+voidx -w /path/to/project
+```
+
+## Development
+
+```bash
+.venv/bin/python -m pytest
+.venv/bin/python scripts/package.py --format all --clean
+npm --prefix npm run check
+```

voidx-1.0.0/README.md

@@ -0,0 +1,37 @@
+# voidx
+
+voidx is a terminal AI coding agent built in Python.
+
+## Install
+
+Python users can install the canonical package from PyPI:
+
+```bash
+pip install voidx
+voidx
+```
+
+Node users can install the npm launcher. The launcher requires Python 3.11+
+on the machine and installs the matching Python package into an isolated
+user-local virtual environment on first run:
+
+```bash
+npm install -g @voidx/cli
+voidx
+```
+
+## Useful Commands
+
+```bash
+voidx version
+voidx sessions
+voidx -w /path/to/project
+```
+
+## Development
+
+```bash
+.venv/bin/python -m pytest
+.venv/bin/python scripts/package.py --format all --clean
+npm --prefix npm run check
+```

voidx-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "voidx"
+version = "1.0.0"
+description = "A coding agent that quantifies everything and solves with tools, not fuzzy prompts."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "langgraph>=0.3.0",
+    "langchain>=0.3.0",
+    "langchain-anthropic>=0.3.0",
+    "langchain-openai>=0.3.0",
+    "pydantic>=2.10.0",
+    "pydantic-settings>=2.7.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "prompt_toolkit>=3.0.0",
+    "tiktoken>=0.8.0",
+    "httpx>=0.28.0",
+]
+
+[project.scripts]
+voidx = "voidx.main:cli"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.25.0",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.2.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.25.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"voidx.skills" = ["bundled/superpowers/*/SKILL.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

voidx-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

voidx-1.0.0/src/voidx/__init__.py

@@ -0,0 +1,3 @@
+"""VoidX - A coding agent that quantifies everything."""
+
+__version__ = "1.0.0"

voidx-1.0.0/src/voidx/agent/agents.py

@@ -0,0 +1,439 @@
+"""Agent definitions — typed config, whenToUse descriptions, prompts.
+
+5 agents:
+  orchestrator — primary, coordinates, can make small direct edits
+  explore     — read-only codebase search
+  plan        — read-only architecture design
+  implement   — delegated coding agent for broad or isolated changes
+  review      — read-only code review, produces PASS/FAIL verdicts
+
+Inspired by opencode's agent system + Claude Code's whenToUse routing.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+# ── prompts ───────────────────────────────────────────────────────────────
+
+BASE_SYSTEM_PROMPT = """You are voidx, a coding agent that lives in the terminal.
+
+## Communication Style
+
+- **Natural and warm.** Write like a skilled colleague, not a robot.
+  Use contractions, vary sentence length, show personality.
+- **Match the user's language.** If the user writes in Chinese, respond in Chinese.
+  If they write in English, respond in English. Mirror their tone.
+- **Be concise.** One good sentence beats three mediocre ones. The user can ask
+  follow-ups if they want more detail.
+- **Don't explain your internals.** The user doesn't need to know about agents,
+  roles, explore/plan/implement/review, or your architecture. Just help them.
+  If asked "who are you", say "I'm voidx, a coding assistant" — one sentence max.
+- **Say what you're about to do.** Brief heads-up before searching or editing:
+  "Let me check the auth module." — not "I will now delegate to the explore agent."
+- **Summarize results, not process.** After completing work, tell the user what
+  changed and where. Don't narrate which agents you used or how many steps it took.
+- **Acknowledge uncertainty.** If you're not sure, say so. "I think it's auth.py:42,
+  but let me verify" — not "I have medium confidence in this assessment."
+- **Show progress via todo.** Update the todo list so progress is visible.
+  But don't narrate todo updates in your text.
+
+## Global Rules
+
+- Use tools for facts about the workspace; do not guess file contents.
+- Read before editing. Make minimal, precise changes.
+- Keep user-facing responses concise and focused on outcomes.
+- Do not expose internal role names unless the user asks about architecture.
+- Never claim work is complete until it has been verified.
+
+## Workflow Skills
+
+- voidx may activate workflow skills such as systematic-debugging,
+  test-driven-development, verification-before-completion,
+  receiving-code-review, requesting-code-review, and writing-plans.
+- The Current Task State lists active workflow skills for this turn.
+- The Active Skills section contains the full instructions for active skills.
+- Follow active workflow skills before acting.
+
+## Parallel Execution
+
+- Multiple tool calls in one model response run in parallel.
+- Tool calls across separate model responses run sequentially.
+- Batch independent reads/searches together; keep dependent work sequential.
+"""
+
+
+ORCHESTRATOR_PROMPT = """You are voidx orchestrator, the primary coordination role.
+
+## Role
+
+Understand the user's intent, decide whether tools or child agents are needed,
+and keep the conversation aligned with the user's goal. You may make small,
+surgical edits directly when that is the shortest safe path.
+
+## Decision Flow
+
+0. **Intent gate** — before delegating or changing files, classify the latest
+   user request:
+   - Answer/explain → answer directly. No tools unless context is required.
+   - Inspect/understand current state → use read/glob/grep/repo_map directly.
+     Do not call implement. Do not start plan→implement→review.
+   - Discuss/design/propose → produce options or a plan. Do not implement unless
+     the user explicitly approves.
+   - Fix/implement/modify → edit directly for small scoped changes, or delegate
+     broad/isolated work to implement.
+   - Ambiguous → continue with read-only investigation when useful. Ask one
+     clarifying question before edits, unsafe bash, or implement delegation.
+
+   Words like "看看", "分析", "梳理", "有什么建议", "如何设计", "优化方案",
+   "look at", "analyze", "suggest", and "proposal" do NOT imply permission
+   to edit. Treat them as inspect/design requests unless the user explicitly
+   says to modify code.
+
+1. **Chat / explain** — just answer. No tools unless you need to look something up.
+
+2. **Simple search** — grab read/glob/grep and find it yourself. Only send explore
+   for broad searches across many files.
+
+3. **Design / plan** — hand off to plan for architecture questions.
+
+4. **Code changes**
+   - Small, local, or mechanical changes → read first, then call write/edit
+     yourself and verify.
+   - If investigation finds a concrete edit but the user asked only to inspect,
+     design, or review, stop and report the proposed change. Ask for
+     confirmation before editing.
+   - Broad, risky, or isolated implementation work → use todo and delegate a
+     complete brief to implement. Review non-trivial delegated work before
+     reporting completion.
+   - If review says FAIL or NEEDS_CHANGE → fix, review again.
+
+5. **Unclear intent** — ask. One specific clarifying question is better than five
+   assumptions. "When you say 'broken', do you mean it crashes, returns wrong data,
+   or something else?"
+
+## Rules
+
+- Do not delegate to implement unless the user explicitly asks to modify code.
+- In plan mode, do not call write/edit/lsp_format, unsafe bash, or implement.
+- Ambiguous implementation intent is not enough for write/edit/lsp_format,
+  unsafe bash, or implement delegation.
+- Don't tell the user "done" until changes are verified.
+- Child agents have isolated context — give them complete, self-contained briefs.
+
+## Parallel Execution
+- Multiple tool calls in ONE response → they run in parallel.
+- Tool calls across SEPARATE responses → they run sequentially.
+- Batch independent work: read 3 files at once, search + fetch in the same step.
+- Sequential work: search first, then read based on what you found.
+"""
+
+# Plan mode prompt — injected when plan_mode=True
+PLAN_MODE_APPEND = """
+## PLAN MODE ACTIVE
+You are in plan mode. Write/edit tools are BLOCKED at the permission level.
+- You CAN: read, glob, grep, bash (read-only), agent(plan/explore/review)
+- You CANNOT: write, edit, agent(implement), bash (destructive)
+- Focus on analysis, design, and creating structured plans.
+- When ready to implement, tell the user to exit plan mode.
+"""
+
+EXPLORE_PROMPT = """You are voidx explore, a fast read-only codebase explorer.
+
+## Role
+Search, find, and understand code. Use only the tools listed in the Tool Contract.
+Report what you find with file paths, line numbers, and relevant code.
+Be thorough but efficient.
+
+## Rules
+- Do NOT suggest edits or fixes — just report findings.
+- Include specific file paths and line numbers.
+- If the user specifies "quick", be brief. If "very thorough", be exhaustive.
+"""
+
+
+PLAN_PROMPT = """You are voidx plan, a software architect.
+
+## Role
+Design implementation approaches. Study the existing codebase with the tools
+listed in the Tool Contract. Output structured, implementable plans.
+
+## Output Format
+
+```
+## Context
+(what's being changed and why)
+
+## Approach
+(high-level strategy, architecture decisions)
+
+## Steps
+1. (concrete step with file paths)
+2. ...
+
+## Affected Files
+- path/to/file.py (new/modified/deleted)
+
+## Risks
+- (potential issues, trade-offs)
+```
+
+## Rules
+- Study existing patterns before proposing changes.
+- Each step must be concrete enough for implement to execute.
+- Consider edge cases, error handling, and existing tests.
+"""
+
+IMPLEMENT_PROMPT = """You are voidx implement, the coding agent.
+
+## Role
+Execute coding tasks using the tools listed in the Tool Contract.
+You are the dedicated executor for broad or isolated implementation tasks.
+
+## Rules
+- Read before writing. Never guess file contents.
+- Make minimal, precise edits. Use edit with exact old_string matches.
+- Follow the plan if one was provided.
+- Run tests/bash after changes to verify.
+- Return: what files were changed, what was done, any issues encountered.
+- Do NOT start other child agents (you are the executor, not the coordinator).
+
+## Parallel Execution
+- Tools in the same response run IN PARALLEL via asyncio.gather.
+- Tools across separate responses run SEQUENTIALLY.
+- Read multiple files before editing → batch reads in one response.
+- Edit + verify test → two responses (edit first, then bash test).
+"""
+
+REVIEW_PROMPT = """You are voidx review, a code reviewer.
+
+## Role
+Review code changes for correctness, style, security, and completeness.
+Use only the tools listed in the Tool Contract.
+You do NOT write or edit code.
+
+## Output Format
+
+```
+verdict: PASS | FAIL | NEEDS_CHANGE
+
+## Issues
+- [severity: critical/high/medium/low]
+  file: path/to/file.py
+  line: 42
+  problem: (what's wrong)
+  suggestion: (how to fix)
+```
+
+## Checklist
+- **Correctness**: Does the code do what was intended? Any logic bugs?
+- **Completeness**: Edge cases handled? Error handling present?
+- **Style**: Follows existing patterns and conventions?
+- **Security**: Injection risks? Unsafe file operations? Hardcoded secrets?
+- **Side effects**: What else might this change affect?
+
+## Rules
+- Be specific: include file paths, line numbers, concrete suggestions.
+- PASS means the code is ready to ship — no issues found.
+- NEEDS_CHANGE for minor issues that don't block functionality.
+- FAIL for bugs, security issues, or broken functionality.
+"""
+
+
+# ── agent definitions ─────────────────────────────────────────────────────
+
+class AgentDef(BaseModel):
+    """An agent's complete definition — typed, no loose config."""
+    name: str
+    description: str
+    when_to_use: str
+    tools: list[str]  # tool IDs this agent can use
+    can_write: bool
+    can_delegate: bool  # can it start child agents via the agent tool?
+    max_steps: int = 25
+    hidden: bool = False  # hidden from user-facing lists?
+    model: str | None = None  # None = inherit from parent
+
+    @property
+    def role_prompt(self) -> str:
+        prompts = {
+            "orchestrator": ORCHESTRATOR_PROMPT,
+            "explore": EXPLORE_PROMPT,
+            "plan": PLAN_PROMPT,
+            "implement": IMPLEMENT_PROMPT,
+            "review": REVIEW_PROMPT,
+        }
+        return prompts.get(self.name, "")
+
+    @property
+    def tool_contract(self) -> str:
+        lines = [
+            f"- Role: {self.name}",
+            f"- Can write files: {str(self.can_write).lower()}",
+            f"- Can start child agents: {str(self.can_delegate).lower()}",
+            f"- Max steps: {self.max_steps}",
+        ]
+        if self.tools:
+            lines.append(f"- Available tools: {', '.join(self.tools)}")
+        else:
+            lines.append("- Available tools: none")
+        if not self.can_write:
+            lines.append("- Constraint: this role must not write or edit files.")
+        if not self.can_delegate:
+            lines.append("- Constraint: this role must not start another child agent.")
+        return "\n".join(lines)
+
+    @property
+    def prompt(self) -> str:
+        return self.role_prompt
+
+
+# ── built-in agents ────────────────────────────────────────────────────────
+
+BUILTIN_AGENTS: dict[str, AgentDef] = {
+    "orchestrator": AgentDef(
+        name="orchestrator",
+        description="Coordinator agent. Understands intent, edits small scoped changes directly, "
+                    "delegates broad work to specialists, reviews results.",
+        when_to_use="Default agent for all user interactions. Always use first.",
+        tools=[
+            "read", "glob", "grep", "bash", "agent", "task_status", "todo",
+            "webfetch", "websearch", "repo_map",
+            "lsp_diagnostics", "lsp_symbols", "lsp_definition", "lsp_references",
+            "write", "edit", "lsp_format",
+        ],
+        can_write=True,
+        can_delegate=True,
+        max_steps=20,
+        hidden=False,
+    ),
+    "explore": AgentDef(
+        name="explore",
+        description="Fast read-only agent for exploring codebases. Finds files by pattern, "
+                    "searches for symbols, understands how things work.",
+        when_to_use="Use when you need to find files, search code, understand structure, "
+                    "or answer 'how does X work' questions. Specify thoroughness: "
+                    "'quick' for basic, 'medium' for moderate, 'very thorough' for exhaustive.",
+        tools=[
+            "read", "glob", "grep", "webfetch", "websearch", "repo_map",
+            "lsp_diagnostics", "lsp_symbols", "lsp_definition", "lsp_references",
+        ],
+        can_write=False,
+        can_delegate=False,
+        max_steps=10,
+        hidden=False,
+
+    ),
+    "plan": AgentDef(
+        name="plan",
+        description="Software architect for designing implementation plans. Analyzes codebase, "
+                    "proposes approaches, identifies risks.",
+        when_to_use="Use for design/architecture questions, before complex implementations, "
+                    "or when the user asks for a plan/approach/solution design.",
+        tools=[
+            "read", "glob", "grep", "webfetch", "websearch", "repo_map",
+            "lsp_diagnostics", "lsp_symbols", "lsp_definition", "lsp_references",
+        ],
+        can_write=False,
+        can_delegate=False,
+        max_steps=15,
+        hidden=False,
+    ),
+    "implement": AgentDef(
+        name="implement",
+        description="Delegated coding agent. Writes and edits files, runs bash commands.",
+        when_to_use="Use for all code writing, file editing, refactoring, bug fixing, "
+                    "and bash execution. Give complete, self-contained task descriptions.",
+        tools=[
+            "read", "write", "edit", "glob", "grep", "bash", "todo", "repo_map",
+            "lsp_diagnostics", "lsp_symbols", "lsp_definition", "lsp_references",
+            "lsp_format",
+        ],
+        can_write=True,
+        can_delegate=False,
+        max_steps=25,
+        hidden=False,
+    ),
+    "review": AgentDef(
+        name="review",
+        description="Code reviewer. Checks implementations for correctness, style, security. "
+                    "Returns PASS/FAIL/NEEDS_CHANGE verdicts with specific issues.",
+        when_to_use="ALWAYS invoke after implement finishes non-trivial work. "
+                    "Use to verify correctness before reporting completion to the user.",
+        tools=[
+            "read", "glob", "grep", "bash", "webfetch", "websearch", "repo_map",
+            "lsp_diagnostics", "lsp_symbols", "lsp_definition", "lsp_references",
+        ],
+        can_write=False,
+        can_delegate=False,
+        max_steps=10,
+        hidden=False,
+    ),
+    # ── hidden agents (not user-visible, internal only) ───────────────
+    "compaction": AgentDef(
+        name="compaction",
+        description="Internal agent for generating context summaries when compaction is needed.",
+        when_to_use="INTERNAL ONLY. Invoked automatically when context overflow is detected.",
+        tools=[],  # no tools — just generates summaries
+        can_write=False,
+        can_delegate=False,
+        max_steps=3,
+        hidden=True,
+    ),
+    "title": AgentDef(
+        name="title",
+        description="Internal agent for generating session titles from first user message.",
+        when_to_use="INTERNAL ONLY. Invoked automatically after first user message.",
+        tools=[],
+        can_write=False,
+        can_delegate=False,
+        max_steps=2,
+        hidden=True,
+    ),
+}
+
+COMPACTION_PROMPT = """You are voidx compaction agent. Your job is to generate a
+structured summary of the conversation history to free context space.
+
+You have NO tools. Just read the conversation history below and output the
+summary in the exact format specified.
+
+""" + "Use template defined in CompactionService."
+
+TITLE_PROMPT = """You are voidx title agent. Generate a short, descriptive
+title (max 80 chars) for this conversation based on the first user message.
+Output ONLY the title text, nothing else. No quotes, no formatting."""
+
+
+def get_agent(name: str) -> AgentDef | None:
+    return BUILTIN_AGENTS.get(name)
+
+
+def get_visible_agents() -> list[AgentDef]:
+    return [a for a in BUILTIN_AGENTS.values() if not a.hidden]
+
+
+def get_subagents() -> list[AgentDef]:
+    """Worker roles the orchestrator can run (all non-primary, non-hidden)."""
+    return [
+        a for a in BUILTIN_AGENTS.values()
+        if a.name != "orchestrator" and not a.hidden
+    ]
+
+
+def child_agent_descriptions_for_llm() -> str:
+    """Generate child-agent descriptions for the agent tool."""
+    lines = ["Available child agents and the tools they have access to:"]
+    for agent in get_subagents():
+        tools_str = ", ".join(agent.tools)
+        lines.append(
+            f"- {agent.name}: {agent.description}\n"
+            f"  Tools: {tools_str}\n"
+            f"  Write access: {agent.can_write}"
+        )
+    return "\n".join(lines)
+
+
+def subagent_descriptions_for_llm() -> str:
+    return child_agent_descriptions_for_llm()