voidx 1.0.0__py3-none-any.whl

voidx/__init__.py

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

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()

voidx/agent/attachments.py

@@ -0,0 +1,235 @@
+"""Parse and materialize user file attachments."""
+
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp"}
+MAX_TEXT_ATTACHMENT_BYTES = 200_000
+MAX_IMAGE_ATTACHMENT_BYTES = 5_000_000
+_ATTACHMENT_RE = re.compile(r'(?<!\S)@(?:"([^"]+)"|(\S+))')
+
+
+@dataclass(frozen=True)
+class Attachment:
+    path: Path
+    rel_path: str
+    kind: str
+    mime_type: str
+    size: int
+
+
+@dataclass
+class UserMessagePayload:
+    raw_text: str
+    clean_text: str
+    display_text: str
+    title_text: str
+    content: str | list[dict[str, Any]]
+    content_format: str
+    attachments: list[Attachment] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def parse_structured_content(content: str, content_format: str) -> str | list[dict[str, Any]]:
+    if content_format != "structured":
+        return content
+    try:
+        parsed = json.loads(content)
+    except Exception:
+        return content
+    return parsed if isinstance(parsed, list) else content
+
+
+def serialize_message_content(content: str | list[dict[str, Any]]) -> tuple[str, str]:
+    if isinstance(content, list):
+        return json.dumps(content, ensure_ascii=False), "structured"
+    return content, "text"
+
+
+def build_user_message_payload(user_text: str, workspace: str) -> UserMessagePayload:
+    workspace_path = Path(workspace).resolve()
+    tokens = _attachment_tokens(user_text)
+    removed_spans: list[tuple[int, int]] = []
+    attachments: list[Attachment] = []
+    warnings: list[str] = []
+    text_sections: list[str] = []
+    image_parts: list[dict[str, Any]] = []
+
+    for start, end, raw_path in tokens:
+        resolved = _resolve_workspace_path(workspace_path, raw_path)
+        if resolved is None:
+            warnings.append(f"Attachment skipped outside workspace: {raw_path}")
+            continue
+        if not resolved.exists() or not resolved.is_file():
+            warnings.append(f"Attachment not found: {raw_path}")
+            continue
+        removed_spans.append((start, end))
+        rel_path = _relative_path(workspace_path, resolved)
+        mime_type = mimetypes.guess_type(str(resolved))[0] or "application/octet-stream"
+        size = resolved.stat().st_size
+        kind = "image" if is_image_path(resolved) else "file"
+        attachment = Attachment(resolved, rel_path, kind, mime_type, size)
+        attachments.append(attachment)
+
+        if kind == "image":
+            if size > MAX_IMAGE_ATTACHMENT_BYTES:
+                warnings.append(f"Image skipped because it is too large: {rel_path}")
+                continue
+            image_parts.append(_image_part(resolved, mime_type))
+            continue
+
+        section, warning = _text_file_section(attachment)
+        if warning:
+            warnings.append(warning)
+        if section:
+            text_sections.append(section)
+
+    clean_text = _normalize_text(_remove_spans(user_text, removed_spans))
+    text_content = _build_text_content(clean_text, attachments, text_sections)
+    content: str | list[dict[str, Any]]
+    content_format = "text"
+    if image_parts:
+        content = [{"type": "text", "text": text_content}, *image_parts]
+        content_format = "structured"
+    else:
+        content = text_content
+
+    display_text = _display_text(clean_text, attachments)
+    title_text = clean_text or (f"Attached {attachments[0].rel_path}" if attachments else user_text)
+    return UserMessagePayload(
+        raw_text=user_text,
+        clean_text=clean_text,
+        display_text=display_text,
+        title_text=title_text,
+        content=content,
+        content_format=content_format,
+        attachments=attachments,
+        warnings=warnings,
+    )
+
+
+def is_image_path(path: Path | str) -> bool:
+    return Path(path).suffix.lower() in IMAGE_EXTENSIONS
+
+
+def _attachment_tokens(text: str) -> list[tuple[int, int, str]]:
+    return [
+        (match.start(), match.end(), match.group(1) or match.group(2) or "")
+        for match in _ATTACHMENT_RE.finditer(text)
+    ]
+
+
+def _remove_spans(text: str, spans: list[tuple[int, int]]) -> str:
+    if not spans:
+        return text
+    result: list[str] = []
+    last = 0
+    for start, end in spans:
+        result.append(text[last:start])
+        result.append(" ")
+        last = end
+    result.append(text[last:])
+    return "".join(result)
+
+
+def _resolve_workspace_path(workspace: Path, raw_path: str) -> Path | None:
+    candidate = Path(raw_path).expanduser()
+    resolved = candidate.resolve() if candidate.is_absolute() else (workspace / candidate).resolve()
+    try:
+        resolved.relative_to(workspace)
+    except ValueError:
+        return None
+    return resolved
+
+
+def _relative_path(workspace: Path, path: Path) -> str:
+    try:
+        return path.relative_to(workspace).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _image_part(path: Path, mime_type: str) -> dict[str, Any]:
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return {
+        "type": "image_url",
+        "image_url": {"url": f"data:{mime_type};base64,{encoded}"},
+    }
+
+
+def _text_file_section(attachment: Attachment) -> tuple[str, str]:
+    raw = attachment.path.read_bytes()
+    truncated = len(raw) > MAX_TEXT_ATTACHMENT_BYTES
+    if truncated:
+        raw = raw[:MAX_TEXT_ATTACHMENT_BYTES]
+    if b"\x00" in raw:
+        return (
+            f"Attached binary file: {attachment.rel_path} ({attachment.mime_type}, {attachment.size} bytes).",
+            "",
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        text = raw.decode("utf-8", errors="replace")
+    suffix = ""
+    warning = ""
+    if truncated:
+        omitted = attachment.size - MAX_TEXT_ATTACHMENT_BYTES
+        suffix = f"\n\n[Attachment truncated: omitted {omitted} bytes]"
+        warning = f"Attachment truncated: {attachment.rel_path}"
+    lang = _language_from_path(attachment.rel_path)
+    return f"Attached file: {attachment.rel_path}\n```{lang}\n{text}{suffix}\n```", warning
+
+
+def _language_from_path(path: str) -> str:
+    suffix = Path(path).suffix.lower().lstrip(".")
+    mapping = {
+        "py": "python",
+        "js": "javascript",
+        "ts": "typescript",
+        "tsx": "tsx",
+        "jsx": "jsx",
+        "json": "json",
+        "md": "markdown",
+        "sh": "bash",
+        "yml": "yaml",
+        "yaml": "yaml",
+        "html": "html",
+        "css": "css",
+    }
+    return mapping.get(suffix, suffix)
+
+
+def _build_text_content(clean_text: str, attachments: list[Attachment], text_sections: list[str]) -> str:
+    parts: list[str] = []
+    if clean_text:
+        parts.append(clean_text)
+    if attachments:
+        image_lines = [f"- {item.rel_path} ({item.mime_type}, {item.size} bytes)" for item in attachments if item.kind == "image"]
+        if image_lines:
+            parts.append("Attached images:\n" + "\n".join(image_lines))
+    parts.extend(text_sections)
+    if parts:
+        return "\n\n".join(parts)
+    return "Please review the attached file."
+
+
+def _display_text(clean_text: str, attachments: list[Attachment]) -> str:
+    if not attachments:
+        return clean_text
+    names = ", ".join(item.rel_path for item in attachments[:3])
+    if len(attachments) > 3:
+        names += f", +{len(attachments) - 3} more"
+    base = clean_text or "Attached files"
+    return f"{base}\n[attachments: {names}]"
+
+
+def _normalize_text(text: str) -> str:
+    return re.sub(r"[ \t]+", " ", text).strip()