voidx 3.7.5__tar.gz → 3.8.0__tar.gz

voidx-3.8.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: voidx
+Version: 3.8.0
+Summary: A coding agent that quantifies everything and solves with tools, not fuzzy prompts.
+Author: chikhamx
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: tiktoken>=0.8.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: websockets>=14
+Requires-Dist: pathspec>=0.12
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: Pillow>=10.0.0; platform_system == "Windows"
+Provides-Extra: gemini
+Requires-Dist: langchain-google-genai>=4.0.0; extra == "gemini"
+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"
+Dynamic: license-file
+
+# 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/master/scripts/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/chikhamx/voidx/master/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
+python -m pip install voidx voidx-cli
+voidx
+```
+
+### npm
+
+```bash
+npm install -g @chikhamx/voidx
+voidx
+```
+
+## Upgrade
+
+Upgrade both Python packages together so the core and terminal UI stay on the
+same version:
+
+```bash
+python -m pip install --upgrade voidx voidx-cli
+```
+
+For npm installations, upgrade the npm package instead:
+
+```bash
+npm update -g @chikhamx/voidx
+```
+
+The one-line installers can be rerun to repair or upgrade their managed
+environment.
+
+### From source
+
+```bash
+git clone https://github.com/chikhamx/voidx.git
+cd voidx
+pip install -e .
+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-3.8.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "voidx"
+dynamic = ["version"]
+description = "A coding agent that quantifies everything and solves with tools, not fuzzy prompts."
+license = {text = "MIT"}
+authors = [{name = "chikhamx"}]
+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",
+    "tiktoken>=0.8.0",
+    "httpx>=0.28.0",
+    "websockets>=14",
+    "pathspec>=0.12",
+    "jsonschema>=4.21",
+	    "Pillow>=10.0.0; platform_system == 'Windows'",
+]
+
+[project.scripts]
+voidx = "voidx.main:cli"
+
+[project.optional-dependencies]
+gemini = ["langchain-google-genai>=4.0.0"]
+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.dynamic]
+version = {attr = "voidx.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"voidx.skills" = [
+    "bundled/*/SKILL.md",
+]
+"voidx.data" = [
+    "documents/**/*.md",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src", "tui"]
+testpaths = ["src/tests", "tui/tests"]

voidx-3.8.0/src/tests/test_agent/application/test_services.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import asyncio
+
+import pytest
+
+from voidx.agent.application.compaction_service import CompactionService
+from voidx.agent.application.session_service import SessionService
+from voidx.agent.application.tool_service import ToolService
+from voidx.agent.application.turn_service import TurnService
+from voidx.agent.domain.compaction import CompactionResult
+from voidx.agent.domain.events import AgentEventKind
+from voidx.agent.domain.state import AgentRuntime
+from voidx.agent.ports.tools import ToolExecutionResult
+
+
+@dataclass
+class MemorySessionStore:
+    runtimes: dict[str, AgentRuntime] = field(default_factory=dict)
+    cleared: list[str] = field(default_factory=list)
+
+    async def load_runtime(self, session_id: str) -> AgentRuntime:
+        return self.runtimes.get(session_id, AgentRuntime()).model_copy(deep=True)
+
+    async def save_runtime(self, session_id: str, runtime: AgentRuntime) -> None:
+        self.runtimes[session_id] = runtime.model_copy(deep=True)
+
+    async def clear_runtime(self, session_id: str) -> None:
+        self.cleared.append(session_id)
+        self.runtimes.pop(session_id, None)
+
+
+@pytest.mark.asyncio
+async def test_session_service_restores_persists_and_clears_runtime():
+    stored = AgentRuntime(compaction_summary="saved", session_time="2026-07-19 CST")
+    store = MemorySessionStore(runtimes={"s1": stored})
+    service = SessionService(store)
+
+    restored = await service.restore_runtime("s1")
+    restored.compaction_summary = "updated"
+    await service.persist_runtime("s1", restored)
+    await service.clear_runtime("s1")
+
+    assert restored.session_time == "2026-07-19 CST"
+    assert store.cleared == ["s1"]
+    assert "s1" not in store.runtimes
+
+
+@dataclass
+class FakeCompactionEngine:
+    result: CompactionResult | None
+    calls: list[tuple[list, list | None, bool, bool, bool]] = field(default_factory=list)
+
+    async def compact(self, messages, session_messages=None, *, force=False, ask=True, preflight=False):
+        self.calls.append((messages, session_messages, force, ask, preflight))
+        return self.result
+
+
+@pytest.mark.asyncio
+async def test_compaction_service_applies_result_and_emits_semantic_event():
+    result = CompactionResult(
+        summary="summary",
+        removed_messages=["old"],
+        live_messages=["new"],
+        tail_id="tail-1",
+    )
+    engine = FakeCompactionEngine(result)
+    events = []
+    service = CompactionService(engine, events.append)
+    messages = ["old", "new"]
+
+    removed, tail_id = await service.compact_live_messages(messages, force=True, ask=False)
+
+    assert messages == ["new"]
+    assert removed == ["old"]
+    assert tail_id == "tail-1"
+    assert events[0].kind is AgentEventKind.COMPACTION_COMPLETED
+
+
+@dataclass
+class FakePermission:
+    allowed: bool
+    calls: list[tuple[str, dict]] = field(default_factory=list)
+
+    async def authorize(self, tool_name: str, arguments: dict) -> bool:
+        self.calls.append((tool_name, arguments))
+        return self.allowed
+
+
+@dataclass
+class FakeTools:
+    result: ToolExecutionResult
+    calls: list[tuple[str, dict]] = field(default_factory=list)
+
+    async def execute(self, tool_name: str, arguments: dict) -> ToolExecutionResult:
+        self.calls.append((tool_name, arguments))
+        return self.result
+
+
+@pytest.mark.asyncio
+async def test_tool_service_checks_permission_before_execution():
+    permission = FakePermission(allowed=False)
+    tools = FakeTools(ToolExecutionResult(output="should not run"))
+
+    result = await ToolService(permission, tools).execute("write", {"path": "x"})
+
+    assert result.denied is True
+    assert tools.calls == []
+
+
+@dataclass
+class FakeTurnEngine:
+    fail: bool = False
+    calls: list[tuple[str, AgentRuntime, str | None]] = field(default_factory=list)
+
+    async def run(
+        self,
+        user_text: str,
+        runtime: AgentRuntime,
+        *,
+        display_text: str | None = None,
+        context=None,
+    ) -> AgentRuntime:
+        self.calls.append((user_text, runtime, display_text))
+        if self.fail:
+            raise RuntimeError("engine failed")
+        return runtime.model_copy(update={"compaction_summary": "completed"})
+
+
+@dataclass
+class MemoryEvents:
+    events: list = field(default_factory=list)
+
+    def publish(self, event) -> None:
+        self.events.append(event)
+
+
+@pytest.mark.asyncio
+async def test_turn_service_orders_events_and_persists_success():
+    sessions = MemorySessionStore()
+    events = MemoryEvents()
+    service = TurnService(FakeTurnEngine(), sessions, events)
+
+    runtime = await service.run("s1", "hello", AgentRuntime(), display_text="focus")
+
+    assert runtime.compaction_summary == "completed"
+    assert [event.kind for event in events.events] == [
+        AgentEventKind.TURN_STARTED,
+        AgentEventKind.TURN_COMPLETED,
+    ]
+    assert sessions.runtimes["s1"].compaction_summary == "completed"
+
+
+@pytest.mark.asyncio
+async def test_turn_service_persists_failure_and_emits_failed_event():
+    sessions = MemorySessionStore()
+    events = MemoryEvents()
+    service = TurnService(FakeTurnEngine(fail=True), sessions, events)
+
+    with pytest.raises(RuntimeError, match="engine failed"):
+        await service.run("s1", "hello", AgentRuntime())
+
+    assert "s1" in sessions.runtimes
+    assert [event.kind for event in events.events] == [
+        AgentEventKind.TURN_STARTED,
+        AgentEventKind.TURN_FAILED,
+    ]
+
+
+@pytest.mark.asyncio
+async def test_turn_service_cancel_persists_and_propagates_cancellation():
+    class CancelledEngine:
+        async def run(self, user_text, runtime, *, display_text=None, context=None):
+            raise asyncio.CancelledError
+
+
+    sessions = MemorySessionStore()
+    events = MemoryEvents()
+    service = TurnService(CancelledEngine(), sessions, events)
+
+    with pytest.raises(asyncio.CancelledError):
+        await service.run("s1", "hello", AgentRuntime())
+
+    assert "s1" in sessions.runtimes
+    assert events.events[-1].metadata["cancelled"] is True

voidx-3.8.0/src/tests/test_agent/domain/test_compaction.py

@@ -0,0 +1,53 @@
+from langchain_core.messages import HumanMessage
+
+from voidx.agent.domain.compaction import CompactionResult, PreflightCompactionResult
+from voidx.agent.infrastructure.langgraph.runtime.compaction_coordinator import (
+    CompactionResult as CoordinatorCompactionResult,
+)
+from voidx.agent.infrastructure.langgraph.runtime.compaction_coordinator import (
+    PreflightCompactionResult as CoordinatorPreflightCompactionResult,
+)
+
+
+def test_compaction_dtos_have_one_domain_source() -> None:
+    assert CoordinatorCompactionResult is CompactionResult
+    assert CoordinatorPreflightCompactionResult is PreflightCompactionResult
+
+
+def test_preflight_result_converts_domain_compaction_metadata() -> None:
+    removed = [HumanMessage(content="old")]
+    result = CompactionResult(
+        summary="summary",
+        removed_messages=removed,
+        live_messages=[HumanMessage(content="new")],
+        tail_id="tail-1",
+        metadata={
+            "removed_message_count": 3,
+            "retained_turn_count": 2,
+            "pre_tokens": 100,
+            "post_tokens": 40,
+            "post_compaction_target": 50,
+            "compaction_reason": "threshold",
+        },
+    )
+
+    preflight = PreflightCompactionResult.from_compaction_result(result)
+
+    assert preflight.model_dump() == {
+        "compacted": True,
+        "summary": "summary",
+        "removed_message_count": 3,
+        "retained_turn_count": 2,
+        "pre_tokens": 100,
+        "post_tokens": 40,
+        "post_target_tokens": 50,
+        "tail_anchor_id": "tail-1",
+        "fallback": False,
+        "reason": "threshold",
+    }
+
+
+def test_empty_preflight_result_is_not_compacted() -> None:
+    assert PreflightCompactionResult.from_compaction_result(None) == PreflightCompactionResult(
+        compacted=False
+    )

voidx-3.8.0/src/tests/test_agent/domain/test_events.py

@@ -0,0 +1,12 @@
+from voidx.agent.domain.events import AgentEvent, AgentEventKind
+
+
+def test_agent_event_is_presentation_agnostic() -> None:
+    event = AgentEvent(
+        kind=AgentEventKind.TURN_STARTED,
+        message="turn started",
+        metadata={"thread_id": "thread-1"},
+    )
+
+    assert event.kind is AgentEventKind.TURN_STARTED
+    assert event.metadata == {"thread_id": "thread-1"}

voidx-3.8.0/src/tests/test_agent/domain/test_import_boundaries.py

@@ -0,0 +1,53 @@
+import ast
+from pathlib import Path
+
+
+
+AGENT_ROOT = Path(__file__).resolve().parents[3] / "voidx" / "agent"
+DOMAIN_ROOT = AGENT_ROOT / "domain"
+
+
+def _imports(path: Path) -> set[str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    modules: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            modules.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            modules.add(node.module)
+    return modules
+
+
+def test_agent_internal_modules_import_runtime_task_state_directly() -> None:
+    offenders = [
+        path.relative_to(AGENT_ROOT).as_posix()
+        for path in AGENT_ROOT.rglob("*.py")
+        if "voidx.agent.task_state" in _imports(path)
+    ]
+
+    assert offenders == []
+
+
+
+
+def test_domain_has_no_infrastructure_dependencies() -> None:
+    forbidden_prefixes = (
+        "voidx.agent.infrastructure.langgraph.runtime",
+        "voidx.config",
+        "voidx.memory",
+        "voidx.permission",
+        "voidx.tools",
+        "voidx.ui",
+        "voidx.workflow",
+        "langgraph",
+    )
+    offenders = {
+        path.name: sorted(
+            module
+            for module in _imports(path)
+            if module.startswith(forbidden_prefixes)
+        )
+        for path in DOMAIN_ROOT.glob("*.py")
+    }
+
+    assert {path: imports for path, imports in offenders.items() if imports} == {}

voidx-3.8.0/src/tests/test_agent/domain/test_persistence_mapper.py

@@ -0,0 +1,48 @@
+from voidx.agent.domain.state import AgentRuntime
+from voidx.agent.infrastructure.runtime_state_mapper import (
+    agent_runtime_from_snapshot,
+    snapshot_from_agent_runtime,
+)
+from voidx.memory.service import RuntimeStateSnapshot
+from voidx.runtime import (
+    GoalSpec,
+    InteractionMode,
+    TaskIntent,
+    TaskState,
+    TodoRunState,
+    WorkflowRoute,
+)
+
+
+def test_agent_runtime_snapshot_round_trip_preserves_persisted_json() -> None:
+    snapshot = RuntimeStateSnapshot(
+        interaction_mode=InteractionMode.GOAL,
+        task_state=TaskState(
+            current_intent=TaskIntent.CODING,
+            previous_intent=TaskIntent.GENERAL,
+            current_goal=GoalSpec(desc="unify agent state"),
+            workflow_route=WorkflowRoute(join="tdd", leave="verify"),
+            todo_state=TodoRunState.model_validate(
+                {
+                    "summary": "0/1 done · 1 active",
+                    "total": 1,
+                    "active": 1,
+                    "active_items": [
+                        {"id": "domain", "content": "create domain", "status": "active"}
+                    ],
+                    "items": [
+                        {"id": "domain", "content": "create domain", "status": "active"}
+                    ],
+                    "updated_at": "2026-07-19T00:00:00+08:00",
+                }
+            ),
+        ),
+        compaction_summary="summary",
+        session_time="2026-07-19 CST",
+    )
+
+    runtime = agent_runtime_from_snapshot(snapshot)
+    restored = snapshot_from_agent_runtime(runtime)
+
+    assert isinstance(runtime, AgentRuntime)
+    assert restored.model_dump(mode="json") == snapshot.model_dump(mode="json")

voidx-3.8.0/src/tests/test_agent/domain/test_state.py

@@ -0,0 +1,42 @@
+from voidx.agent.domain.state import AgentRuntime
+from voidx.agent.domain.turn import TurnPhase, advance_turn
+from voidx.runtime import GoalSpec, InteractionMode, TaskIntent, TaskState
+
+
+def test_agent_runtime_owns_domain_state_without_graph() -> None:
+    runtime = AgentRuntime(
+        interaction_mode=InteractionMode.GOAL,
+        task_state=TaskState(
+            current_intent=TaskIntent.CODING,
+            current_goal=GoalSpec(desc="unify agent state"),
+        ),
+        compaction_summary="existing summary",
+        session_time="2026-07-19 CST",
+    )
+
+    assert runtime.task_state.current_goal == GoalSpec(desc="unify agent state")
+    assert runtime.compaction_summary == "existing summary"
+    assert runtime.session_time == "2026-07-19 CST"
+
+
+def test_turn_state_conversion_is_pure_and_preserves_runtime() -> None:
+    runtime = AgentRuntime(compaction_summary="summary")
+
+    running = advance_turn(runtime, TurnPhase.RUNNING)
+    committed = advance_turn(running, TurnPhase.COMMITTED)
+
+    assert runtime.turn_phase is TurnPhase.INITIAL
+    assert running.turn_phase is TurnPhase.RUNNING
+    assert committed.turn_phase is TurnPhase.COMMITTED
+    assert committed.compaction_summary == "summary"
+
+
+def test_turn_state_rejects_invalid_transition() -> None:
+    runtime = AgentRuntime(turn_phase=TurnPhase.COMMITTED)
+
+    try:
+        advance_turn(runtime, TurnPhase.RUNNING)
+    except ValueError as exc:
+        assert "committed -> running" in str(exc)
+    else:
+        raise AssertionError("invalid turn transition was accepted")