voidx 1.0.1__tar.gz → 2.0.0__tar.gz

{voidx-1.0.1 → voidx-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidx
-Version: 1.0.1
+Version: 2.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
@@ -14,7 +14,7 @@ Requires-Dist: typer>=0.15.0
 Requires-Dist: rich>=13.9.0
 Requires-Dist: tiktoken>=0.8.0
 Requires-Dist: httpx>=0.28.0
-Requires-Dist: websockets>=16.0
+Requires-Dist: websockets>=14
 Provides-Extra: dev
 Requires-Dist: build>=1.2.0; extra == "dev"
 Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -26,22 +26,46 @@ voidx is a terminal AI coding agent built in Python.
 
 ## Install
 
-Python users can install the canonical package from PyPI:
+### One-line install (no Python or npm required)
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/chikhamx/voidx/main/scripts/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/chikhamx/voidx/main/scripts/install.ps1 | iex
+```
+
+The installer downloads a standalone Python runtime and sets up voidx in an
+isolated environment — nothing else is needed on your machine.
+
+### pip
 
 ```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:
+### npm
 
 ```bash
 npm install -g @chikhamx/voidx
 voidx
 ```
 
+### China / slow network
+
+Set mirror environment variables before running any install method:
+
+```bash
+export VOIDX_PYTHON_MIRROR=https://npmmirror.com/mirrors/python-standalone
+export VOIDX_PIP_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
 ## Useful Commands
 
 ```bash

voidx-2.0.0/README.md

@@ -0,0 +1,61 @@
+# voidx
+
+voidx is a terminal AI coding agent built in Python.
+
+## Install
+
+### One-line install (no Python or npm required)
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/chikhamx/voidx/main/scripts/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/chikhamx/voidx/main/scripts/install.ps1 | iex
+```
+
+The installer downloads a standalone Python runtime and sets up voidx in an
+isolated environment — nothing else is needed on your machine.
+
+### pip
+
+```bash
+pip install voidx
+voidx
+```
+
+### npm
+
+```bash
+npm install -g @chikhamx/voidx
+voidx
+```
+
+### China / slow network
+
+Set mirror environment variables before running any install method:
+
+```bash
+export VOIDX_PYTHON_MIRROR=https://npmmirror.com/mirrors/python-standalone
+export VOIDX_PIP_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+## 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.1 → voidx-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "voidx"
-version = "1.0.1"
+version = "2.0.0"
 description = "A coding agent that quantifies everything and solves with tools, not fuzzy prompts."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -15,7 +15,7 @@ dependencies = [
     "rich>=13.9.0",
     "tiktoken>=0.8.0",
     "httpx>=0.28.0",
-    "websockets>=16.0",
+    "websockets>=14",
 ]
 
 [project.scripts]
@@ -43,7 +43,10 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-"voidx.skills" = ["bundled/superpowers/*/SKILL.md"]
+"voidx.skills" = [
+    "bundled/superpowers/*/SKILL.md",
+    "bundled/superpowers/*/templates/*.md",
+]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{voidx-1.0.1 → voidx-2.0.0}/src/voidx/__init__.py

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

{voidx-1.0.1 → voidx-2.0.0}/src/voidx/agent/agents.py

@@ -83,8 +83,8 @@ surgical edits directly when that is the shortest safe path.
      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.
+   - Ambiguous → continue with read-only investigation when useful. Use clarify
+     for one structured question before edits, unsafe bash, or implement delegation.
 
    Words like "看看", "分析", "梳理", "有什么建议", "如何设计", "优化方案",
    "look at", "analyze", "suggest", and "proposal" do NOT imply permission
@@ -92,11 +92,15 @@ surgical edits directly when that is the shortest safe path.
    says to modify code.
 
 1. **Chat / explain** — just answer. No tools unless you need to look something up.
+   If Current Task State says intent is chat or ambiguous, but the user request
+   appears to require workspace action, call on_intent before other workspace tools.
 
 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.
+3. **Design / plan** — hand off to plan for architecture questions. For
+   non-trivial implementation plans, call plan_checkpoint before changing files,
+   running write-capable commands, or delegating implement.
 
 4. **Code changes**
    - Small, local, or mechanical changes → read first, then call write/edit
@@ -109,9 +113,9 @@ surgical edits directly when that is the shortest safe path.
      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?"
+5. **Unclear intent** — ask through clarify. 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
 
@@ -119,6 +123,8 @@ surgical edits directly when that is the shortest safe path.
 - 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.
+- Child agents do not interact with the user. If a child plan result needs user
+  approval or clarification, call plan_checkpoint or clarify yourself.
 - Don't tell the user "done" until changes are verified.
 - Child agents have isolated context — give them complete, self-contained briefs.
 
@@ -257,14 +263,12 @@ class AgentDef(BaseModel):
 
     @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, "")
+        if self.name in PROMPTLESS_AGENTS:
+            return ""
+        try:
+            return ROLE_PROMPTS[self.name]
+        except KeyError as exc:
+            raise ValueError(f"No role prompt registered for agent: {self.name}") from exc
 
     @property
     def tool_contract(self) -> str:
@@ -284,9 +288,14 @@ class AgentDef(BaseModel):
             lines.append("- Constraint: this role must not start another child agent.")
         return "\n".join(lines)
 
-    @property
-    def prompt(self) -> str:
-        return self.role_prompt
+ROLE_PROMPTS = {
+    "orchestrator": ORCHESTRATOR_PROMPT,
+    "explore": EXPLORE_PROMPT,
+    "plan": PLAN_PROMPT,
+    "implement": IMPLEMENT_PROMPT,
+    "review": REVIEW_PROMPT,
+}
+PROMPTLESS_AGENTS = {"compaction", "title"}
 
 
 # ── built-in agents ────────────────────────────────────────────────────────
@@ -298,6 +307,7 @@ BUILTIN_AGENTS: dict[str, AgentDef] = {
                     "delegates broad work to specialists, reviews results.",
         when_to_use="Default agent for all user interactions. Always use first.",
         tools=[
+            "on_intent", "clarify", "plan_checkpoint",
             "read", "glob", "grep", "bash", "agent", "task_status", "todo",
             "webfetch", "websearch", "repo_map",
             "lsp_diagnostics", "lsp_symbols", "lsp_definition", "lsp_references",
@@ -397,9 +407,7 @@ 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."
+summary in the exact format specified."""
 
 TITLE_PROMPT = """You are voidx title agent. Generate a short, descriptive
 title (max 80 chars) for this conversation based on the first user message.
@@ -433,7 +441,3 @@ def child_agent_descriptions_for_llm() -> str:
             f"  Write access: {agent.can_write}"
         )
     return "\n".join(lines)
-
-
-def subagent_descriptions_for_llm() -> str:
-    return child_agent_descriptions_for_llm()

voidx-2.0.0/src/voidx/agent/graph/__init__.py

@@ -0,0 +1,5 @@
+"""Agent graph — LangGraph state machine with 5-agent system."""
+
+from voidx.agent.graph.core import VoidXGraph
+
+__all__ = ["VoidXGraph"]

{voidx-1.0.1/src/voidx/agent/graph_components → voidx-2.0.0/src/voidx/agent/graph}/compaction.py

@@ -2,28 +2,40 @@
 
 from __future__ import annotations
 
-from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+from typing import TYPE_CHECKING
 
-from voidx.agent.graph_components.runtime import console, ui
-from voidx.agent.graph_components.streaming import extract_text, stream_llm
+from langchain_core.messages import AIMessage, SystemMessage
+
+from voidx.agent.message_rows import messages_from_rows
+from voidx.agent.graph.runtime import console, ui
+from voidx.agent.graph.streaming import extract_text, stream_llm
+from voidx.llm.compaction import COMPACTION_MAX_RETRIES, CompactionService
 from voidx.llm.provider import resolve_protocol
 from voidx.llm.usage import estimate_context_tokens, estimate_message_tokens, extract_token_usage
 from voidx.memory.context_frames import save_context_frame_from_messages
-from voidx.ui.console import StreamingRenderer
-from voidx.ui.dock import dock
-from voidx.ui.events import StatusFinished, StatusUpdated, ui_events, via_events
+from voidx.ui.output.console import StreamingRenderer
+from voidx.ui.output.dock import dock
+from voidx.ui.output.events import StatusFinished, StatusUpdated, ui_events, via_events
+
+if TYPE_CHECKING:
+    from voidx.agent.graph.contracts import GraphCompactionHost
 
 
 class GraphCompactionMixin:
     async def _maybe_compact(
-        self,
+        self: GraphCompactionHost,
         messages: list,
-        session_msgs: list,
+        session_msgs: list | None = None,
         *,
         force: bool = False,
         ask: bool = True,
     ) -> tuple[list | None, str | None]:
-        """Check overflow and compact if needed."""
+        """Check overflow and compact if needed.
+
+        Returns the messages removed from the live context and the persisted
+        tail anchor id when one is available. Fallback truncation has no stable
+        tail anchor, so it returns None for the second value.
+        """
         total_tokens = estimate_context_tokens(messages, self.config.model.model)
         tokens = {"total": total_tokens, "input": total_tokens, "output": 0, "reasoning": 0}
 
@@ -73,56 +85,83 @@ class GraphCompactionMixin:
                     detail=f"fallback truncation, keeping last {keep} messages",
                     stage="compacting",
                 ))
-                await ui_events.emit(StatusFinished(
-                    status_id="compaction",
-                    label=f"Compaction fallback kept last {keep} messages",
-                    remove=False,
-                ))
             else:
                 ui.print(f"[dim]Aggressive truncation: keeping last {keep} messages[/dim]")
-            # Remove old messages, keep system + last N
-            system_msgs = [m for m in messages if isinstance(m, SystemMessage)]
-            other_msgs = [m for m in messages if not isinstance(m, SystemMessage)]
-            messages.clear()
-            messages.extend(system_msgs)
-            messages.extend(other_msgs[-keep:])
-            return messages[:max(0, len(messages) - keep)], None
 
-        # Run compaction agent
-        try:
+            removed = _truncate_to_recent_messages(messages, keep)
+            # Generate a basic summary from the removed messages
+            fallback = CompactionService.fallback_summary(removed)
+            self._pending_summary = fallback
+            self._compaction_summary = fallback
+            self._compaction.compaction_count += 1
+
             if via_events():
-                await ui_events.emit(StatusUpdated(
+                await ui_events.emit(StatusFinished(
                     status_id="compaction",
-                    label="Compacting context",
-                    detail=f"summarizing {len(head_msgs)} old messages",
-                    stage="compacting",
+                    label=f"Compaction fallback kept last {keep} messages (with extracted summary)",
+                    remove=False,
                 ))
-            previous_summary = getattr(self, "_compaction_summary", "") or None
-            summary = await self._run_compaction_agent(head_msgs, previous_summary)
-        except Exception as e:
+            return removed, None
+
+        # Run compaction agent with retries
+        summary = None
+        previous_summary = getattr(self, "_compaction_summary", "") or None
+        last_error: Exception | None = None
+
+        for attempt in range(1, COMPACTION_MAX_RETRIES + 2):  # 1 initial + N retries
+            try:
+                if via_events():
+                    retry_label = f" (attempt {attempt})" if attempt > 1 else ""
+                    await ui_events.emit(StatusUpdated(
+                        status_id="compaction",
+                        label="Compacting context",
+                        detail=f"summarizing {len(head_msgs)} old messages{retry_label}",
+                        stage="compacting",
+                    ))
+                summary = await self._run_compaction_agent(head_msgs, previous_summary)
+                if summary:
+                    break
+            except Exception as e:
+                last_error = e
+                if attempt <= COMPACTION_MAX_RETRIES:
+                    if via_events():
+                        await ui_events.emit(StatusUpdated(
+                            status_id="compaction",
+                            label="Compaction agent failed",
+                            detail=f"{e}; retrying ({attempt}/{COMPACTION_MAX_RETRIES})",
+                            stage="compacting",
+                        ))
+                    else:
+                        ui.print(f"[dim]Compaction agent failed ({e}) — retrying ({attempt}/{COMPACTION_MAX_RETRIES})[/dim]")
+
+        if not summary:
+            # All retries exhausted — fallback truncation with basic summary
             if via_events():
+                err_detail = f"{last_error}; " if last_error else ""
                 await ui_events.emit(StatusUpdated(
                     status_id="compaction",
                     label="Compaction agent failed",
-                    detail=f"{e}; falling back to truncation",
+                    detail=f"{err_detail}falling back to truncation with extracted summary",
                     stage="compacting",
                 ))
             else:
-                ui.print(f"[dim]Compaction agent failed ({e}) — aggressive truncation[/dim]")
+                err_msg = f" ({last_error})" if last_error else ""
+                ui.print(f"[dim]Compaction agent failed{err_msg} — aggressive truncation with summary[/dim]")
             keep = min(6, len(messages))
-            system_msgs = [m for m in messages if isinstance(m, SystemMessage)]
-            other_msgs = [m for m in messages if not isinstance(m, SystemMessage)]
-            messages.clear()
-            messages.extend(system_msgs)
-            messages.extend(other_msgs[-keep:])
+            removed = _truncate_to_recent_messages(messages, keep)
+            # Generate a basic summary from the removed messages
+            fallback = CompactionService.fallback_summary(head_msgs if head_msgs else removed)
+            self._pending_summary = fallback
+            self._compaction_summary = fallback
+            self._compaction.compaction_count += 1
             if via_events():
                 await ui_events.emit(StatusFinished(
                     status_id="compaction",
-                    label=f"Compaction fallback kept last {keep} messages",
+                    label=f"Compaction fallback kept last {keep} messages (with extracted summary)",
                     ok=False,
                     remove=False,
                 ))
-            return messages[:max(0, len(messages) - keep)], None
+            return removed, None
 
         if summary:
             keep_from = len(head_msgs)
@@ -154,7 +193,7 @@ class GraphCompactionMixin:
 
         return head_msgs, tail_id
 
-    async def _ask_compact(self, total_tokens: int) -> bool:
+    async def _ask_compact(self: GraphCompactionHost, total_tokens: int) -> bool:
         choices = [
             ("Compact", "compact", "Summarize older context and continue"),
             ("Skip once", "skip", "Continue without compacting this turn"),
@@ -167,7 +206,7 @@ class GraphCompactionMixin:
         ui.print(f"  [yellow]Context is large ({total_tokens} tokens); compacting automatically.[/yellow]")
         return True
 
-    async def _persist_compaction(self, head_messages: list) -> None:
+    async def _persist_compaction(self: GraphCompactionHost, head_messages: list) -> None:
         if getattr(self, "_session", None) is None:
             return
         if hasattr(self, "_persist_runtime_state"):
@@ -179,42 +218,33 @@ class GraphCompactionMixin:
 
         await delete_messages_through(self._session.id, last_message_id)
 
-    async def _compact_session_history(self, *, force: bool = True) -> bool:
+        # Sync in-memory cache: drop compacted rows
+        cache = getattr(self, "_session_msg_cache", None)
+        if cache is not None:
+            self._session_msg_cache = [r for r in cache if r.id is not None and r.id > last_message_id]
+
+    async def _compact_session_history(self: GraphCompactionHost, *, force: bool = True) -> bool:
         if getattr(self, "_session", None) is None:
             ui.print("[dim]No active session to compact.[/dim]")
             return False
 
-        from voidx.agent.attachments import parse_structured_content
-        from voidx.memory.session import load_messages
-
-        rows = await load_messages(self._session.id)
-        messages = []
-        for row in rows:
-            msg_id = str(row.id) if row.id is not None else None
-            if row.role == "system":
-                messages.append(SystemMessage(content=row.content, id=msg_id))
-            elif row.role == "user":
-                messages.append(HumanMessage(
-                    content=parse_structured_content(row.content, row.content_format),
-                    id=msg_id,
-                ))
-            elif row.role == "assistant":
-                messages.append(AIMessage(
-                    content=parse_structured_content(row.content, row.content_format),
-                    tool_calls=row.tool_calls or [],
-                    id=msg_id,
-                ))
-            elif row.role == "tool":
-                messages.append(ToolMessage(
-                    content=row.content,
-                    tool_call_id=row.tool_call_id or "",
-                    id=msg_id,
-                ))
+        cache = getattr(self, "_session_msg_cache", None)
+        if cache is not None:
+            rows = list(cache)
+        else:
+            from voidx.memory.session import load_messages
+            rows = await load_messages(self._session.id)
+
+        messages = messages_from_rows(rows)
 
         head, _tail_id = await self._maybe_compact(messages, rows, force=force, ask=False)
         return bool(head)
 
-    async def _run_compaction_agent(self, head_messages: list, previous_summary: str | None) -> str | None:
+    async def _run_compaction_agent(
+        self: GraphCompactionHost,
+        head_messages: list,
+        previous_summary: str | None,
+    ) -> str | None:
         """Run the compaction agent to generate a structured summary."""
         from voidx.agent.agents import COMPACTION_PROMPT
 
@@ -266,3 +296,16 @@ def _max_persisted_message_id(messages: list) -> int | None:
         except (TypeError, ValueError):
             continue
     return max(ids) if ids else None
+
+
+def _truncate_to_recent_messages(messages: list, keep: int) -> list:
+    original = list(messages)
+    system_msgs = [m for m in original if isinstance(m, SystemMessage)]
+    other_msgs = [m for m in original if not isinstance(m, SystemMessage)]
+    tail_msgs = other_msgs[-keep:] if keep > 0 else []
+    retained_ids = {id(m) for m in [*system_msgs, *tail_msgs]}
+    removed = [m for m in original if id(m) not in retained_ids]
+    messages.clear()
+    messages.extend(system_msgs)
+    messages.extend(tail_msgs)
+    return removed