voidx 2.3.0__tar.gz → 3.0.0__tar.gz

{voidx-2.3.0 → voidx-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidx
-Version: 2.3.0
+Version: 3.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

{voidx-2.3.0 → voidx-3.0.0}/pyproject.toml

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

{voidx-2.3.0 → voidx-3.0.0}/src/voidx/__init__.py

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

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

@@ -0,0 +1,266 @@
+"""Agent definitions — typed config, whenToUse descriptions, prompts.
+
+voidx uses one agent identity:
+  voidx       — primary identity, also used for isolated child runs
+
+Runtime personas (coordinate/explore/plan/implement/review) are thinking-mode
+labels, not AgentDef ids.
+"""
+
+
+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,
+  personas, 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 persona names unless the user asks about architecture.
+- Never claim work is complete until it has been verified.
+- When Current Task State lists an active workflow gate, that workflow gate takes precedence
+  over persona prompts, delegation rules, and the decision flow below.
+
+## Workflow Runtime
+
+- voidx has a structured workflow runtime.
+- Current Task State is the activation source for this turn's workflow nodes.
+- Workflow Context messages contain structured workflow node definitions as a
+  stable reference library. Follow ONLY nodes listed as active in Current Task
+  State, unless the user explicitly references another node by name.
+- When a node is not listed as active, its definition is reference only. Do not
+  follow its gate, internal workflow steps, or transition instructions.
+- load_skills can return project/global skill bodies for the current turn.
+"""
+
+
+VOIDX_PROMPT = """## Coordination
+
+- Assess before acting.
+- Stay aligned with the user's actual goal.
+- Delegate only when you need to run multiple independent tasks in parallel, or the user explicitly asks for a child agent. Do not delegate single-file reads, simple searches, or straightforward tasks you can do directly.
+- Coordinate the work without exposing internal persona names to the user.
+
+## Persona Model
+
+voidx has five thinking modes (personas). The active persona is shown in Current Task State.
+Switch persona automatically when entering a workflow node.
+
+- **coordinate**: Default. Assess, plan next steps, coordinate work, delegate when parallel speedup is needed.
+- **explore**: Evidence gathering and codebase search. Search broadly, report with concrete paths and lines.
+- **plan**: Design and architecture. Study existing patterns, output structured implementable plans.
+- **implement**: Build and execute. Write minimal precise edits, run tests to verify.
+- **review**: Verify and critique. Check correctness, completeness, style, security. Produce PASS/FAIL verdicts.
+
+## Responsibilities
+
+- Before acting, assess what's already known and what's still needed.
+- Pick the smallest next action that makes progress toward the goal.
+- Only delegate to a child agent when you have multiple independent tasks or the user asks.
+- Only declare work done after running verification (tests, reads, diagnostics).
+
+## Rules
+
+- Subagents do not interact with the user.
+- Runtime workflow gates take precedence over persona prompts and delegation rules.
+"""
+
+CHILD_RUN_CONSTRAINTS = """- Follow the runtime persona shown in Current Task State.
+- Execute only the delegated task in this isolated child run.
+- Do not interact with the user directly.
+- Do not start another child agent.
+- If a tool call fails, report the error clearly and attempt an alternative approach if one exists.
+- Structure your final output with clear sections: what you found, what you did, and what remains uncertain.
+- Runtime workflow gates take precedence over persona prompts and delegation rules."""
+
+# 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 (non-destructive commands only; no file writes, installs, or system changes), 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.
+"""
+
+# ── 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?
+    hidden: bool = False  # hidden from user-facing lists?
+    model: str | None = None  # None = inherit from parent
+    mcp_tools: bool = False  # can see registered MCP tools
+
+    @property
+    def persona_prompt(self) -> str:
+        try:
+            return PERSONA_PROMPTS[self.name]
+        except KeyError as exc:
+            raise ValueError(f"No persona prompt registered for agent: {self.name}") from exc
+
+    @property
+    def tool_contract(self) -> str:
+        lines = [
+            f"- Agent identity: {self.name}",
+            f"- Can write files: {str(self.can_write).lower()}",
+            f"- Can start child agents: {str(self.can_delegate).lower()}",
+        ]
+        if self.tools:
+            lines.append(f"- Available tools: {', '.join(self.tools)}")
+        else:
+            lines.append("- Available tools: none")
+        if self.mcp_tools:
+            lines.append("- MCP tools: available when configured; each call is permission-gated")
+        if not self.can_delegate:
+            lines.append("- Constraint: this agent must not start another child agent.")
+        return "\n".join(lines)
+
+def persona_prompt_for_llm(agent: AgentDef, *, parallel_subagents_enabled: bool = False) -> str:
+    """Return the persona prompt with runtime-gated child-agent scheduling rules."""
+
+    prompt = agent.persona_prompt
+    if agent.name != "voidx":
+        return prompt
+    child_agent_prompt = _parallel_subagents_prompt(
+        enabled=parallel_subagents_enabled,
+    )
+    if not prompt:
+        return child_agent_prompt
+    return f"{prompt.rstrip()}\n\n{child_agent_prompt}"
+
+
+_SCHEDULING_COMMON = """- Each child-agent brief must be complete and self-contained.
+- Keep dependent child-agent work sequential: wait for the result before
+  delegating follow-up work that depends on it.
+- Batch independent read/search tools when useful; keep dependent tool work
+  sequential."""
+
+
+def _parallel_subagents_prompt(*, enabled: bool) -> str:
+    if enabled:
+        return (
+            "## Child-Agent Scheduling\n\n"
+            "- Only start a child agent when you have multiple independent tasks to run in\n"
+            "  parallel, or the user explicitly requests it. Do not delegate work you can do\n"
+            "  directly.\n"
+            "- For independent child-agent tasks, you may issue multiple `agent` tool calls\n"
+            "  in one response. They will run concurrently up to the configured limit.\n"
+            + _SCHEDULING_COMMON
+        )
+    return (
+        "## Child-Agent Scheduling\n\n"
+        "- Only start a child agent when you have multiple independent tasks to run in\n"
+        "  parallel, or the user explicitly requests it. Do not delegate work you can do\n"
+        "  directly.\n"
+        "- Delegate at most one child agent in a response. Wait for that result before\n"
+        "  deciding whether another child agent is needed.\n"
+        + _SCHEDULING_COMMON
+    )
+
+
+# ── built-in agents ────────────────────────────────────────────────────────
+
+BUILTIN_AGENTS: dict[str, AgentDef] = {
+    "voidx": AgentDef(
+        name="voidx",
+        description="Primary 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=[
+            "clarify", "plan_checkpoint", "advance_workflow", "compact_context",
+            "read", "glob", "grep", "bash", "agent", "task_status", "todo", "load_skills",
+            "load_doc_template",
+            "webfetch", "websearch", "repo_map",
+            "lsp",
+            "write", "edit",
+        ],
+        can_write=True,
+        can_delegate=True,
+        hidden=False,
+        mcp_tools=True,
+    ),
+}
+
+
+PERSONA_PROMPTS = {
+    "voidx": VOIDX_PROMPT,
+}
+
+
+CHILD_RUN_TOOLS = [
+    "read", "write", "edit", "glob", "grep", "bash", "todo", "load_skills", "repo_map",
+    "lsp",
+]
+
+
+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]:
+    """Child-run identities voidx can delegate to."""
+    agent = get_agent("voidx")
+    return [child_run_agent_def(agent)] if agent is not None else []
+
+
+def child_run_agent_def(agent: AgentDef) -> AgentDef:
+    """Return the child-run view of the public voidx identity."""
+    tools = CHILD_RUN_TOOLS if agent.name == "voidx" else agent.tools
+    return agent.model_copy(update={
+        "name": "voidx",
+        "description": "Isolated child run of voidx with a requested runtime persona.",
+        "when_to_use": "Use for delegated child work that benefits from isolated context.",
+        "tools": tools,
+        "can_delegate": False,
+    })
+
+
+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)
+        if agent.mcp_tools:
+            tools_str = f"{tools_str}, MCP tools" if tools_str else "MCP tools"
+        lines.append(
+            f"- {agent.name}: {agent.description}\n"
+            f"  Tools: {tools_str}\n"
+            f"  Write access: {agent.can_write}"
+        )
+    return "\n".join(lines)

{voidx-2.3.0 → voidx-3.0.0}/src/voidx/agent/attachments.py

@@ -10,9 +10,10 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from voidx.runtime.attachments import MAX_IMAGE_ATTACHMENT_BYTES
+
 IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp"}
 MAX_TEXT_ATTACHMENT_BYTES = 200_000
-MAX_IMAGE_ATTACHMENT_BYTES = 5_000_000
 MAX_DIR_LISTING_ITEMS = 500
 _DIR_TREE_SKIP = {"__pycache__", ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "dist", "build", ".pytest_cache", ".mypy_cache"}
 _ATTACHMENT_RE = re.compile(r'(?<!\S)(?:@(?:"([^"]+)"|(\S+))|\[image-([^\]]+)\])')

voidx-3.0.0/src/voidx/agent/goal_resolver.py

@@ -0,0 +1,228 @@
+"""Runtime-owned structured goal resolution for top-level turns."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+
+from voidx.runtime.intent import InteractionMode, TaskIntent
+from voidx.runtime.task_state import (
+    GoalResolution,
+    GoalSpec,
+    GoalType,
+    IntentResolution,
+    PlanResolution,
+    TaskState,
+    _default_join_for_goal_type,
+    _default_leave_for_goal_type,
+)
+from voidx.workflow.dag import DEFAULT_WORKFLOW_DAG
+
+
+GOAL_RESOLVER_TIMEOUT_SECONDS = 20
+
+
+async def resolve_goal_for_turn(
+    *,
+    model: Any | None,
+    user_text: str,
+    interaction_mode: str | InteractionMode | None,
+    task_state: TaskState,
+    workspace: str,
+    session_time: str,
+) -> GoalResolution:
+    fallback = GoalResolution(
+        intent=IntentResolution(type=TaskIntent.GENERAL, desc=""),
+        goal=None,
+        plan=None,
+    )
+    if model is None:
+        return _normalize_resolution(fallback, user_text, interaction_mode, task_state)
+
+    structured = getattr(model, "with_structured_output", None)
+    if not callable(structured):
+        return _normalize_resolution(fallback, user_text, interaction_mode, task_state)
+
+    try:
+        runnable = structured(GoalResolution)
+        raw = await asyncio.wait_for(
+            runnable.ainvoke(_resolver_messages(
+                user_text,
+                interaction_mode,
+                task_state,
+                workspace,
+                session_time,
+            )),
+            timeout=GOAL_RESOLVER_TIMEOUT_SECONDS,
+        )
+        resolution = _coerce_resolution(raw)
+    except Exception:
+        resolution = None
+
+    if resolution is None:
+        return _normalize_resolution(fallback, user_text, interaction_mode, task_state)
+    return _normalize_resolution(resolution, user_text, interaction_mode, task_state)
+
+
+def _resolver_messages(
+    user_text: str,
+    interaction_mode: str | InteractionMode | None,
+    task_state: TaskState,
+    workspace: str,
+    session_time: str,
+) -> list:
+    schema = json.dumps(GoalResolution.model_json_schema(), ensure_ascii=False)
+    current_goal = (
+        task_state.current_goal.model_dump(mode="json")
+        if task_state.current_goal is not None
+        else None
+    )
+    context = {
+        "workspace": workspace,
+        "session_time": session_time,
+        "interaction_mode": InteractionMode.parse(interaction_mode).value,
+        "current_intent": task_state.current_intent.value,
+        "current_goal": current_goal,
+
+        "recent_user_texts": task_state.recent_user_texts[-2:],
+        "latest_user_text": user_text,
+    }
+    available_joins = ", ".join(sorted(_ALLOWED_JOIN_NODES))
+    system = (
+        "You are voidx resolving the current user's goal before normal work begins.\n"
+        "Return only structured data matching the GoalResolution schema.\n\n"
+        "Rules:\n"
+        "- intent.type=general only for non-code, non-workspace conversation.\n"
+        "- intent.type=coding for codebase inspection, design, docs, review, debugging, or edits.\n"
+        "- Pick exactly one goal.type when intent is coding and a concrete workspace goal exists.\n"
+        "- plan.join is the workflow node the agent should enter. Required when goal is set; null when goal is null.\n"
+        "- plan.leave is the workflow node after which automatic progression stops. Optional.\n"
+        f"- Available join values: {available_joins}.\n"
+        "- Choose join based on the user's primary intent:\n"
+        "  - debug: user reports a bug, error, crash, or unexpected behavior to investigate.\n"
+        "  - brainstorm: user wants to explore requirements, design a feature, or discuss approach before coding.\n"
+        "  - design-doc: user asks to write or revise a design/spec/PRD/RFC/API doc.\n"
+        "  - plan: user asks to turn a spec or requirements into an implementation plan.\n"
+        "  - tdd: user explicitly asks to implement an already detailed spec or continue an approved implementation.\n"
+        "  - review: user asks for code review or pre-merge review.\n"
+        "  - feedback: user provides review feedback or reviewer comments to act on.\n"
+        "- If the user's intent does not clearly match any join value, set goal to null and plan to null. The agent will work without workflow constraints.\n"
+        "- Do not choose brainstorm when the request already contains an approved or sufficiently detailed spec.\n"
+        "- Do not set join or leave based on vague or ambiguous approval.\n"
+        "- goal and plan are bound: if goal is set, plan must be set with join; if goal is null, plan must be null.\n"
+        f"GoalResolution JSON schema:\n{schema}"
+    )
+    return [
+        SystemMessage(content=system),
+        HumanMessage(content=json.dumps(context, ensure_ascii=False, indent=2)),
+    ]
+
+
+_ALLOWED_JOIN_NODES = {"debug", "brainstorm", "design-doc", "plan", "tdd", "review", "feedback"}
+
+
+def _coerce_resolution(value: object) -> GoalResolution | None:
+    if isinstance(value, GoalResolution):
+        return value
+    if isinstance(value, AIMessage):
+        value = value.content
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except json.JSONDecodeError:
+            return None
+    if isinstance(value, dict) and "parsed" in value:
+        return _coerce_resolution(value.get("parsed"))
+    if isinstance(value, dict):
+        try:
+            return GoalResolution.model_validate(value)
+        except ValueError:
+            return None
+    return None
+
+
+def _normalize_resolution(
+    resolution: GoalResolution,
+    user_text: str,
+    interaction_mode: str | InteractionMode | None,
+    task_state: TaskState,
+) -> GoalResolution:
+    mode = InteractionMode.parse(interaction_mode)
+
+    # Validate join against resolver entry points, and leave against DAG nodes.
+    plan = resolution.plan
+    if plan is not None:
+        if plan.join and plan.join not in _ALLOWED_JOIN_NODES:
+            plan = None
+        elif plan.leave and plan.leave not in DEFAULT_WORKFLOW_DAG.nodes:
+            plan = PlanResolution(join=plan.join, leave=None)
+
+    # plan mode: force design goal + brainstorm
+    if mode == InteractionMode.PLAN:
+        desc = (
+            resolution.goal.desc
+            if resolution.goal is not None and resolution.goal.desc.strip()
+            else user_text
+        )
+        return GoalResolution(
+            intent=IntentResolution(type=TaskIntent.CODING, desc="plan mode forces design goal"),
+            goal=GoalSpec(type=GoalType.DESIGN, desc=desc),
+            plan=PlanResolution(
+                join="brainstorm",
+                leave=plan.leave if plan is not None else None,
+            ),
+        )
+
+    # goal mode: keep current_goal unchanged
+    if mode == InteractionMode.GOAL and task_state.current_goal is not None:
+        current = task_state.current_goal
+        goal = GoalSpec(type=current.type, desc=current.desc)
+        if plan is None:
+            plan = PlanResolution(
+                join=_default_join_for_goal_type(current.type),
+                leave=_default_leave_for_goal_type(current.type),
+            )
+        return GoalResolution(
+            intent=IntentResolution(
+                type=TaskIntent.CODING,
+                desc="goal mode keeps the turn scoped to the current goal",
+            ),
+            goal=goal,
+            plan=plan,
+        )
+
+    # general intent: no goal, no plan
+    if resolution.intent.type == TaskIntent.GENERAL:
+        return GoalResolution(
+            intent=resolution.intent,
+            goal=None,
+            plan=None,
+        )
+
+    # coding intent: fill default join/leave when needed
+    goal = resolution.goal
+    if goal is not None:
+        if plan is None:
+            plan = PlanResolution(
+                join=_default_join_for_goal_type(goal.type),
+                leave=_default_leave_for_goal_type(goal.type),
+            )
+        elif not plan.join:
+            plan = PlanResolution(
+                join=_default_join_for_goal_type(goal.type),
+                leave=plan.leave or _default_leave_for_goal_type(goal.type),
+            )
+        elif not plan.leave:
+            plan = PlanResolution(
+                join=plan.join,
+                leave=_default_leave_for_goal_type(goal.type),
+            )
+
+    return GoalResolution(
+        intent=resolution.intent,
+        goal=goal,
+        plan=plan,
+    )