voidx 3.1.0__tar.gz → 3.1.1__tar.gz

{voidx-3.1.0 → voidx-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidx
-Version: 3.1.0
+Version: 3.1.1
 Summary: A coding agent that quantifies everything and solves with tools, not fuzzy prompts.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{voidx-3.1.0 → voidx-3.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "voidx"
-version = "3.1.0"
+version = "3.1.1"
 description = "A coding agent that quantifies everything and solves with tools, not fuzzy prompts."
 readme = "README.md"
 requires-python = ">=3.11"

{voidx-3.1.0 → voidx-3.1.1}/src/voidx/__init__.py

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

{voidx-3.1.0 → voidx-3.1.1}/src/voidx/agent/goal_resolver.py

@@ -230,8 +230,36 @@ def _truncate_error_text(value: str, limit: int = 2000) -> str:
 
 def _resolver_system_prompt() -> str:
     return (
-        "Resolve this turn into intent, goal, workflow, and kind_hint.\n"
-        "Read the Markdown request. Return only structured data matching the schema at the end."
+        "You are a goal resolver. Classify the user's current turn into intent, goal, workflow, and kind_hint.\n"
+        "\n"
+        "## Output Schema\n"
+        "\n"
+        "Return a JSON object matching this template:\n"
+        "\n"
+        "{\n"
+        '  "intent": "coding" or "general",\n'
+        '  "goal": null or "<short summary of the user\'s request in their language, 1-2 sentences>",\n'
+        '  "workflow": null or "<one of the workflows listed below>",\n'
+        '  "kind_hint": null or "<semantic hint: review | debug | feature | inspect | refactor | test | docs>"\n'
+        "}\n"
+        "\n"
+        "## Field Rules\n"
+        "\n"
+        '- **intent**: "coding" for codebase/workspace work; "general" for non-code conversation.\n'
+        "- **goal**: Short user-language summary when a workflow should start; null otherwise. Must be set exactly when workflow is set, and null exactly when workflow is null.\n"
+        "- **workflow**: The workflow to start, or null. Must be set exactly when goal is set.\n"
+        "- **kind_hint**: Optional semantic hint. Advisory only; never overrides workflow selection.\n"
+        "\n"
+        "## Available Workflows\n"
+        "\n"
+        "- brainstorm: Confirm requirements and design, get user approval\n"
+        "- debug: Locate root cause and confirm fix direction\n"
+        "- design: Produce a structured document that passes the reader test\n"
+        "- feedback: Verify and implement valid review feedback\n"
+        "- plan: Produce an executable implementation plan, get user approval\n"
+        "- review: Initiate structured code review request and collect verdict\n"
+        "- tdd: Complete implementation via TDD cycle, all tests green\n"
+        "- verify: Prove changes reach expected state with reproducible evidence\n"
     )
 
 
@@ -239,52 +267,22 @@ def _resolver_request_markdown(user_text: str, task_state: TaskState) -> str:
     recent_content = _recent_exchanges_content(task_state)
     active = ", ".join(_active_workflow_names(task_state)) or "none"
     goal = task_state.current_goal.label if task_state.current_goal is not None else "none"
-    return "\n".join([
-        "# Goal Resolver Request",
-        "",
-        "## Current State",
+    sections = [
+        "# Context",
         "",
         f"- intent: {task_state.current_intent.value}",
         f"- goal: {goal}",
         f"- active workflows: {active}",
         "",
-        "## Recent Conversation Content",
+        "# Recent Conversation",
         "",
-        "```text",
         recent_content,
-        "```",
         "",
-        "## Current User Content",
+        "# Current User Question",
         "",
-        "```text",
         user_text,
-        "```",
-        "",
-        "## Available Workflows",
-        "",
-        "- brainstorm: Confirm requirements and design, get user approval",
-        "- debug: Locate root cause and confirm fix direction",
-        "- design: Produce a structured document that passes the reader test",
-        "- feedback: Verify and implement valid review feedback",
-        "- plan: Produce an executable implementation plan, get user approval",
-        "- review: Initiate structured code review request and collect verdict",
-        "- tdd: Complete implementation via TDD cycle, all tests green",
-        "- verify: Prove changes reach expected state with reproducible evidence",
-        "",
-        "## Return Fields",
-        "",
-        '- intent: "coding" for codebase/workspace work; "general" for non-code conversation.',
-        "- goal: short user-language summary, or null when no workflow should start.",
-        "- workflow: workflow to start, or null. Must be set exactly when goal is set.",
-        "- kind_hint: optional semantic hint such as review/debug/feature/inspect. Advisory only; never overrides workflow.",
-        "",
-        "## ResolverGoal Schema",
-        "",
-        "- intent: 'coding' | 'general'",
-        "- goal: null or string (short summary of the user's request in their language, 1-2 sentences)",
-        "- workflow: null or one of [brainstorm, debug, design, feedback, plan, review, tdd, verify]",
-        "- kind_hint: null or string (non-authoritative semantic hint; not used for routing)",
-    ])
+    ]
+    return "\n".join(sections)
 
 
 _ALLOWED_JOIN_NODES = {"debug", "brainstorm", "design", "plan", "tdd", "review", "feedback", "verify"}
@@ -405,10 +403,16 @@ def _normalize_resolution(
 def _recent_exchanges_content(task_state: TaskState) -> str:
     blocks: list[str] = []
     for index, exchange in enumerate(task_state.recent_exchanges, start=1):
-        parts = [part for part in (exchange.user_text.strip(), exchange.assistant_text.strip()) if part]
-        if not parts:
+        lines: list[str] = [f"## Turn {index}", ""]
+        user_text = exchange.user_text.strip()
+        assistant_text = exchange.assistant_text.strip()
+        if user_text:
+            lines.append(f"**Human**: {user_text}")
+        if assistant_text:
+            lines.append(f"**Assistant**: {assistant_text}")
+        if len(lines) <= 2:
             continue
-        blocks.append(f"### Content {index}\n\n" + "\n\n".join(parts))
+        blocks.append("\n".join(lines))
     return "\n\n".join(blocks)
 
 

{voidx-3.1.0 → voidx-3.1.1}/src/voidx/agent/graph/compaction.py

@@ -4,7 +4,11 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from voidx.agent.graph.compaction_coordinator import CompactionResult, GraphCompactionCoordinator
+from voidx.agent.graph.compaction_coordinator import (
+    CompactionResult,
+    GraphCompactionCoordinator,
+    PreflightCompactionResult,
+)
 
 if TYPE_CHECKING:
     from voidx.agent.graph.contracts import GraphCompactionHost
@@ -30,36 +34,40 @@ class GraphCompactionMixin:
         *,
         force: bool = False,
         ask: bool = True,
+        preflight: bool = False,
     ) -> tuple[list | None, str | None]:
         return await _compaction_component_for(self).maybe_compact(
             messages,
             session_msgs,
             force=force,
             ask=ask,
+            preflight=preflight,
             run_compaction_agent=self._run_compaction_agent,
             persist_compaction=self._persist_compaction,
         )
 
-    async def _in_turn_compact(
+    async def _preflight_compact_if_needed(
         self: GraphCompactionHost,
         messages: list,
-    ) -> CompactionResult | None:
-        count = getattr(self, "_in_turn_compaction_count", 0) + 1
-        self._in_turn_compaction_count = count
-        if count > 2:
-            return None
-        result = await _compaction_component_for(self).compact_for_live_state(
+        session_msgs: list | None = None,
+        *,
+        force: bool = False,
+        reason: str = "threshold",
+        ask: bool = False,
+    ) -> tuple[CompactionResult | None, PreflightCompactionResult]:
+        result, preflight_result = await _compaction_component_for(self).preflight_compact_if_needed(
             messages,
-            force=True,
-            ask=False,
-            include_summary_message=True,
+            session_msgs,
+            force=force,
+            reason=reason,
+            ask=ask,
             run_compaction_agent=self._run_compaction_agent,
             persist_compaction=self._persist_compaction,
         )
         if result is not None:
             self._file_read_coverage.clear()
             self._file_mtimes.clear()
-        return result
+        return result, preflight_result
 
     async def _ask_compact(self: GraphCompactionHost, total_tokens: int) -> bool:
         return await _compaction_component_for(self).ask_compact(total_tokens)

{voidx-3.1.0 → voidx-3.1.1}/src/voidx/agent/graph/compaction_coordinator.py

@@ -4,9 +4,11 @@ from __future__ import annotations
 
 import logging
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
+from pydantic import BaseModel
+
 from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
 
 from voidx.agent.graph.streaming import extract_text, stream_llm
@@ -47,6 +49,38 @@ class CompactionResult:
     live_messages: list[BaseMessage]
     tail_id: str | None
     fallback: bool = False
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+class PreflightCompactionResult(BaseModel):
+    compacted: bool
+    summary: str = ""
+    removed_message_count: int = 0
+    retained_turn_count: int = 0
+    pre_tokens: int = 0
+    post_tokens: int = 0
+    post_target_tokens: int = 0
+    tail_anchor_id: str = ""
+    fallback: bool = False
+    reason: str = ""
+
+    @classmethod
+    def from_compaction_result(cls, result: CompactionResult | None) -> "PreflightCompactionResult":
+        if result is None:
+            return cls(compacted=False)
+        metadata = result.metadata or {}
+        return cls(
+            compacted=True,
+            summary=result.summary,
+            removed_message_count=int(metadata.get("removed_message_count") or len(result.removed_messages)),
+            retained_turn_count=int(metadata.get("retained_turn_count") or 0),
+            pre_tokens=int(metadata.get("pre_tokens") or 0),
+            post_tokens=int(metadata.get("post_tokens") or 0),
+            post_target_tokens=int(metadata.get("post_compaction_target") or 0),
+            tail_anchor_id=str(metadata.get("tail_anchor_id") or result.tail_id or ""),
+            fallback=bool(metadata.get("fallback") or result.fallback),
+            reason=str(metadata.get("compaction_reason") or ""),
+        )
 
 
 class GraphCompactionCoordinator:
@@ -62,6 +96,7 @@ class GraphCompactionCoordinator:
         *,
         force: bool = False,
         ask: bool = True,
+        preflight: bool = False,
         run_compaction_agent: RunCompactionAgent | None = None,
         persist_compaction: PersistCompaction | None = None,
     ) -> tuple[list | None, str | None]:
@@ -75,6 +110,7 @@ class GraphCompactionCoordinator:
             session_msgs,
             force=force,
             ask=ask,
+            preflight=preflight,
             run_compaction_agent=run_compaction_agent,
             persist_compaction=persist_compaction,
         )
@@ -85,6 +121,34 @@ class GraphCompactionCoordinator:
         messages.extend(result.live_messages)
         return result.removed_messages, result.tail_id
 
+    async def preflight_compact_if_needed(
+        self,
+        messages: list[BaseMessage],
+        session_msgs: list | None = None,
+        *,
+        force: bool = False,
+        reason: str = "threshold",
+        ask: bool = False,
+        run_compaction_agent: RunCompactionAgent | None = None,
+        persist_compaction: PersistCompaction | None = None,
+    ) -> tuple[CompactionResult | None, PreflightCompactionResult]:
+        result = await self.compact_for_live_state(
+            messages,
+            session_msgs,
+            force=force,
+            ask=ask,
+            preflight=True,
+            include_summary_message=False,
+            run_compaction_agent=run_compaction_agent,
+            persist_compaction=persist_compaction,
+        )
+        preflight_result = PreflightCompactionResult.from_compaction_result(result)
+        if preflight_result.compacted and reason and preflight_result.reason in {"", "threshold", "force"}:
+            preflight_result.reason = reason
+            if result is not None:
+                result.metadata["compaction_reason"] = reason
+        return result, preflight_result
+
     async def compact_for_live_state(
         self,
         messages: list[BaseMessage],
@@ -92,6 +156,7 @@ class GraphCompactionCoordinator:
         *,
         force: bool = False,
         ask: bool = True,
+        preflight: bool = False,
         include_summary_message: bool = False,
         run_compaction_agent: RunCompactionAgent | None = None,
         persist_compaction: PersistCompaction | None = None,
@@ -103,7 +168,9 @@ class GraphCompactionCoordinator:
         total_tokens = estimate_context_tokens(messages, host.config.model.model)
         tokens = {"total": total_tokens, "input": total_tokens, "output": 0, "reasoning": 0}
 
-        if not force and not host._compaction.is_overflow(tokens):
+        over_hard = host._compaction.is_overflow(tokens)
+        over_soft = preflight and host._compaction.is_soft_overflow(tokens)
+        if not force and not over_hard and not over_soft:
             return None
 
         if not force and ask and getattr(host.config, "ask_compact", False):
@@ -123,11 +190,7 @@ class GraphCompactionCoordinator:
             await host._ui.events.emit(StatusUpdated(
                 status_id="compaction",
                 label="Compacting context",
-                detail=(
-                    f"{total_tokens} tokens exceed the active context budget"
-                    if not force
-                    else f"manual compaction of {len(messages)} messages"
-                ),
+                detail=_compaction_status_detail(total_tokens, force=force, preflight=preflight),
                 stage="compacting",
             ))
         else:
@@ -142,7 +205,15 @@ class GraphCompactionCoordinator:
             raw_semantic_messages(messages),
             preserve_trailing_ai_tool_calls=True,
         )
-        selection = host._compaction.select_details(semantic_messages)
+        if preflight:
+            selection = host._compaction.select_preflight_details(
+                semantic_messages,
+                model=host.config.model.model,
+            )
+            if not selection.should_compact and (force or over_hard):
+                selection = host._compaction.select_details(semantic_messages)
+        else:
+            selection = host._compaction.select_details(semantic_messages)
         head_msgs, tail_id = selection.head, selection.tail_id
         semantic_tail = semantic_messages[selection.keep_from:]
 
@@ -155,6 +226,18 @@ class GraphCompactionCoordinator:
                 ))
             return None
 
+        base_metadata = _compaction_metadata(
+            host,
+            semantic_messages=semantic_messages,
+            semantic_tail=semantic_tail,
+            total_tokens=total_tokens,
+            force=force,
+            preflight=preflight,
+            over_soft=over_soft,
+            over_hard=over_hard,
+            removed_message_count=len(head_msgs),
+            tail_id=tail_id,
+        )
         summary = None
         previous_summary = getattr(host, "_compaction_summary", "") or None
         last_error: Exception | None = None
@@ -213,6 +296,18 @@ class GraphCompactionCoordinator:
             host._compaction_summary = fallback
             host._compaction.compaction_count += 1
             await persist(head_msgs)
+            live_messages = _live_messages(
+                runtime_prefix,
+                semantic_tail,
+                fallback,
+                include_summary_message=include_summary_message,
+            )
+            metadata = _finish_compaction_metadata(
+                base_metadata,
+                live_messages=live_messages,
+                model=host.config.model.model,
+                fallback=True,
+            )
             if host._ui.via_events():
                 await host._ui.events.emit(StatusFinished(
                     status_id="compaction",
@@ -224,14 +319,10 @@ class GraphCompactionCoordinator:
             return CompactionResult(
                 summary=fallback,
                 removed_messages=list(head_msgs),
-                live_messages=_live_messages(
-                    runtime_prefix,
-                    semantic_tail,
-                    fallback,
-                    include_summary_message=include_summary_message,
-                ),
+                live_messages=live_messages,
                 tail_id=tail_id,
                 fallback=True,
+                metadata=metadata,
             )
 
         if summary:
@@ -258,17 +349,25 @@ class GraphCompactionCoordinator:
         else:
             return None
 
+        live_messages = _live_messages(
+            runtime_prefix,
+            semantic_tail,
+            summary,
+            include_summary_message=include_summary_message,
+        )
+        metadata = _finish_compaction_metadata(
+            base_metadata,
+            live_messages=live_messages,
+            model=host.config.model.model,
+            fallback=False,
+        )
         return CompactionResult(
             summary=summary,
             removed_messages=list(head_msgs),
-            live_messages=_live_messages(
-                runtime_prefix,
-                semantic_tail,
-                summary,
-                include_summary_message=include_summary_message,
-            ),
+            live_messages=live_messages,
             tail_id=tail_id,
             fallback=False,
+            metadata=metadata,
         )
 
     async def ask_compact(self, total_tokens: int) -> bool:
@@ -450,6 +549,81 @@ def _content_type_summary(content: object) -> str:
     return type(content).__name__
 
 
+def _compaction_status_detail(total_tokens: int, *, force: bool, preflight: bool) -> str:
+    if force:
+        return "manual compaction"
+    if preflight:
+        return f"{total_tokens} tokens reached the preflight compaction threshold"
+    return f"{total_tokens} tokens exceed the active context budget"
+
+
+def _compaction_metadata(
+    host: GraphCompactionHost,
+    *,
+    semantic_messages: list[BaseMessage],
+    semantic_tail: list[BaseMessage],
+    total_tokens: int,
+    force: bool,
+    preflight: bool,
+    over_soft: bool,
+    over_hard: bool,
+    removed_message_count: int,
+    tail_id: str | None,
+) -> dict[str, object]:
+    return {
+        "compaction_reason": _compaction_reason(
+            force=force,
+            preflight=preflight,
+            over_soft=over_soft,
+            over_hard=over_hard,
+        ),
+        "pre_tokens": total_tokens,
+        "soft_threshold": host._compaction.soft_threshold(),
+        "hard_threshold": int(host._compaction.context_limit * 0.90),
+        "post_compaction_target": host._compaction.post_compaction_target(),
+        "removed_message_count": removed_message_count,
+        "retained_turn_count": len(host._compaction._turns(semantic_tail)),
+        "current_user_preserved": _latest_user_preserved(semantic_messages, semantic_tail),
+        "tail_anchor_id": tail_id or "",
+        "inline_compaction_enabled": bool(getattr(host.config, "inline_compaction_enabled", False)),
+    }
+
+
+def _finish_compaction_metadata(
+    metadata: dict[str, object],
+    *,
+    live_messages: list[BaseMessage],
+    model: str,
+    fallback: bool,
+) -> dict[str, object]:
+    return {
+        **metadata,
+        "post_tokens": estimate_context_tokens(live_messages, model),
+        "fallback": fallback,
+    }
+
+
+def _compaction_reason(*, force: bool, preflight: bool, over_soft: bool, over_hard: bool) -> str:
+    if force:
+        return "force"
+    if over_hard:
+        return "hard_threshold"
+    if preflight and over_soft:
+        return "soft_threshold"
+    return "threshold"
+
+
+def _latest_user_preserved(
+    semantic_messages: list[BaseMessage],
+    semantic_tail: list[BaseMessage],
+) -> bool:
+    latest_user = next(
+        (message for message in reversed(semantic_messages) if isinstance(message, HumanMessage)),
+        None,
+    )
+    return latest_user is None or any(message is latest_user for message in semantic_tail)
+
+
 def _compaction_request_text(previous_summary: str | None) -> str:
     previous_summary_section = ""
     if previous_summary:

{voidx-3.1.0 → voidx-3.1.1}/src/voidx/agent/graph/contracts.py

@@ -20,7 +20,11 @@ from voidx.runtime.ui_port import AgentUiPort
 from voidx.tools.service import ToolRegistry, TaskTracker
 
 if TYPE_CHECKING:
-    from voidx.agent.graph.compaction_coordinator import CompactionResult, GraphCompactionCoordinator
+    from voidx.agent.graph.compaction_coordinator import (
+        CompactionResult,
+        GraphCompactionCoordinator,
+        PreflightCompactionResult,
+    )
     from voidx.agent.graph.runtime_guards import RuntimeGuardState
     from voidx.agent.graph.session_runtime import GraphSessionRuntime
     from voidx.agent.graph.tool_executor import GraphToolExecutor
@@ -39,7 +43,6 @@ class GraphCompactionHost(Protocol):
     _usage_stats: UsageStats
     _compaction: CompactionService
     _compaction_coordinator: GraphCompactionCoordinator
-    _in_turn_compaction_count: int
     _pending_summary: str | None
     _compaction_summary: str
     _session_msg_cache: list[Any] | None
@@ -53,11 +56,17 @@ class GraphCompactionHost(Protocol):
         *,
         force: bool = False,
         ask: bool = True,
+        preflight: bool = False,
     ) -> tuple[list[BaseMessage] | None, str | None]: ...
-    async def _in_turn_compact(
+    async def _preflight_compact_if_needed(
         self,
         messages: list[BaseMessage],
-    ) -> CompactionResult | None: ...
+        session_msgs: list[Any] | None = None,
+        *,
+        force: bool = False,
+        reason: str = "threshold",
+        ask: bool = False,
+    ) -> tuple[CompactionResult | None, PreflightCompactionResult]: ...
     async def _ask_compact(self, total_tokens: int) -> bool: ...
     async def _persist_compaction(self, head_messages: list[BaseMessage]) -> None: ...
     async def _compact_session_history(self, *, force: bool = True) -> bool: ...

{voidx-3.1.0 → voidx-3.1.1}/src/voidx/agent/graph/core/_voidx_graph.py

@@ -114,7 +114,6 @@ class VoidXGraph(
         self._current_messages: list[BaseMessage] | None = None
         self._pending_summary: str | None = None
         self._compaction_summary: str = ""
-        self._in_turn_compaction_count: int = 0
         self._session_date: str = session_date(session)
         self._session_msg_cache: list | None = None
         self._context_cache = ContextCompilerCache()