core-runtime 0.1.1__py3-none-any.whl

will/agents/conversational/helpers.py

@@ -0,0 +1,116 @@
+# src/will/agents/conversational/helpers.py
+
+"""
+Helper functions for ConversationalAgent.
+Contains pure functions extracted from the main agent class.
+
+V2 (v2.2.0): RequestInterpreter now handles intent parsing and keyword extraction.
+These helpers focus on bridging TaskStructure → ContextBuilder and formatting.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG = load_operational_config().misc
+
+
+def _build_llm_prompt(
+    user_message: str,
+    context_package: dict[str, Any],
+    format_context_items_func,
+    task_context: str = "",
+) -> str:
+    """
+    Build the prompt to send to the LLM.
+
+    Includes:
+    - System context about CORE
+    - Task interpretation metadata (if provided)
+    - The extracted context package
+    - The user's question
+    - Instructions for the LLM
+
+    Args:
+        user_message: Original user query
+        context_package: Minimal context from ContextBuilder
+        format_context_items_func: Function to format context items
+        task_context: Optional task interpretation metadata from RequestInterpreter
+
+    Returns:
+        Complete prompt for LLM
+    """
+    # Extract key info from context package
+    context_items = context_package.get("context", [])
+    num_items = len(context_items)
+
+    # Format context items for the LLM
+    formatted_context = format_context_items_func(context_items)
+
+    # Build prompt with optional task context
+    task_section = f"\n{task_context}\n" if task_context else ""
+
+    prompt = f"""You are CORE's conversational assistant, helping a developer understand their codebase.
+
+The developer asked: "{user_message}"
+{task_section}
+I've extracted {num_items} relevant pieces of context from the codebase:
+
+{formatted_context}
+
+Please provide a clear, concise answer to their question based on this context.
+
+Instructions:
+- Focus on answering their specific question
+- Use code examples from the context when helpful
+- Be conversational and friendly
+- If the context doesn't contain enough information, say so
+- Keep your response under 500 words
+
+Your response:"""
+
+    return prompt
+
+
+def _format_context_items(items: list[dict[str, Any]]) -> str:
+    """
+    Format context items into readable text for LLM.
+
+    Args:
+        items: List of context items from ContextPackage
+
+    Returns:
+        Formatted string representation with structure and code
+    """
+    if not items:
+        return "(No specific context found - the question may be too general)"
+
+    formatted = []
+    for i, item in enumerate(items, 1):
+        name = item.get("name", "Unknown")
+        item_type = item.get("item_type", "unknown")
+        path = item.get("path", "")
+        summary = item.get("summary", "")
+        content = item.get("content", "")
+
+        formatted.append(f"--- Context Item {i}: {name} ({item_type}) ---")
+        if path:
+            formatted.append(f"Location: {path}")
+        if summary:
+            formatted.append(f"Summary: {summary}")
+        if content:
+            # Truncate very long content
+            if len(content) > _CFG.conversation_max_content_chars:
+                content = (
+                    content[: _CFG.conversation_max_content_chars] + "\n... (truncated)"
+                )
+            formatted.append(f"Code:\n{content}")
+        formatted.append("")  # Blank line between items
+
+    return "\n".join(formatted)

will/agents/execution_agent.py

@@ -0,0 +1,294 @@
+# src/will/agents/execution_agent.py
+
+"""
+ExecutionAgent - The Contractor: Executes validated code blueprints.
+
+Constitutional Role:
+- Applies DetailedPlans created by the SpecificationAgent
+- Enforces write-permission boundaries
+- Returns what was written for audit trails
+- Respects atomic actions for all mutations
+
+PHASE 1 ENHANCEMENT:
+- Now captures files_written during execution
+- Enables crate extraction and post-execution inspection
+- Provides source-of-truth for what changed
+
+UNIX PHILOSOPHY ENHANCEMENT:
+- Test generation failures don't block refactoring workflows
+- Refactoring job: Make code modular (even if tests break)
+- Testing job: Regenerate tests AFTER (separate workflow)
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from shared.action_types import ActionResult
+from shared.logger import getLogger
+from shared.models.workflow_models import DetailedPlan, ExecutionResults
+from will.agents.traced_agent_mixin import TracedAgentMixin
+from will.orchestration.decision_tracer import DecisionTracer
+
+
+if TYPE_CHECKING:
+    from body.atomic.executor import ActionExecutor
+
+logger = getLogger(__name__)
+
+# Params that are meaningful only for file mutation actions.
+# fix.* and sync.* actions operate repo-wide and must not receive these.
+_FILE_SCOPED_PARAMS = frozenset(
+    {"file_path", "code", "symbol_name", "justification", "tag"}
+)
+
+# Action prefixes whose implementations do not accept file-scoped params.
+_REPO_WIDE_PREFIXES = ("fix.", "sync.")
+
+
+def _params_to_dict(params) -> dict:
+    """
+    Safely convert step params to a plain dict.
+
+    Handles both TaskParams (Pydantic model) and plain dicts — defensive
+    because DetailedPlanStep.params is typed as dict[str, Any] but the
+    pipeline may pass TaskParams objects.
+    """
+    if params is None:
+        return {}
+    if hasattr(params, "model_dump"):
+        return params.model_dump(exclude_none=True)
+    if isinstance(params, dict):
+        return params
+    return {}
+
+
+def _strip_params_for_action(action_id: str, params_dict: dict) -> dict:
+    """
+    Remove file-scoped params that repo-wide actions do not accept.
+
+    fix.* and sync.* actions (fix.imports, fix.format, sync.db, etc.)
+    operate on the whole repo and have no file_path parameter in their
+    signatures. Passing these causes a TypeError at invocation time.
+    """
+    if any(action_id.startswith(prefix) for prefix in _REPO_WIDE_PREFIXES):
+        return {k: v for k, v in params_dict.items() if k not in _FILE_SCOPED_PARAMS}
+    return params_dict
+
+
+# ID: a1b2c3d4-e5f6-7890-abcd-ef0123456789
+class ExecutionAgent(TracedAgentMixin):
+    """
+    The Contractor: Executes validated code blueprints.
+
+    Skips steps that failed code generation and enforces
+    constitutional write-permission boundaries.
+
+    ENHANCED: Captures files_written for crate extraction.
+
+    UNIX PHILOSOPHY: Test failures are advisory during refactoring.
+    """
+
+    def __init__(self, executor: ActionExecutor, write: bool = False):
+        """
+        Initialize the ExecutionAgent.
+
+        Args:
+            executor: The ActionExecutor (The Body's Gateway).
+            write: Whether to apply changes (True) or simulate (False).
+        """
+        self.executor = executor
+        self.write = write
+        self.tracer = DecisionTracer()
+
+        logger.info(
+            "ExecutionAgent initialized (Contractor Mode: write=%s)", self.write
+        )
+
+    # ID: b2c3d4e5-f678-90ab-cdef-0123456789ab
+    async def execute_plan(
+        self,
+        detailed_plan: DetailedPlan,
+    ) -> ExecutionResults:
+        """
+        Execute a DetailedPlan step-by-step.
+
+        Returns simple ExecutionResults matching the dataclass definition.
+        """
+        start_time = time.time()
+
+        logger.info(
+            "🗂️ Construction Phase: Applying %d spec-validated steps...",
+            detailed_plan.step_count,
+        )
+
+        results: list[ActionResult] = []
+        success_count = 0
+        failure_count = 0
+        aborted_at_step: int | None = None
+
+        # PHASE 1 ENHANCEMENT: Capture files as they're written
+        files_written: dict[str, str] = {}
+
+        for i, step in enumerate(detailed_plan.steps, 1):
+            logger.info(
+                "  [Step %d/%d] Executing: %s...",
+                i,
+                detailed_plan.step_count,
+                step.description,
+            )
+
+            # Check if Step was marked as failed during Engineering phase
+            if step.metadata.get("generation_failed", False):
+                error_msg = step.metadata.get("error", "Code generation failed")
+                logger.warning(
+                    "    ↳ ⚠️ Skipping step - code generation failed: %s", error_msg
+                )
+                result = ActionResult(
+                    action_id=step.action,
+                    ok=False,
+                    data={
+                        "error": error_msg,
+                        "error_type": "CodeGenerationFailed",
+                        "skipped": True,
+                    },
+                    duration_sec=0.0,
+                )
+                results.append(result)
+                failure_count += 1
+
+                # UNIX PHILOSOPHY FIX: Test failures don't block refactoring
+                # Tests are regenerated AFTER code is modular
+                is_test_step = (
+                    "test" in step.action.lower() or "test" in step.description.lower()
+                )
+
+                if step.is_critical and not is_test_step:
+                    aborted_at_step = i
+                    logger.error("🛑 Critical step failed during generation. Aborting.")
+                    break
+                elif is_test_step:
+                    logger.info(
+                        "    ↳ 📋 Test generation failed (expected during refactoring) - continuing..."
+                    )
+
+                continue
+
+            # Execute the step
+            result = await self._execute_step(step, i)
+            results.append(result)
+
+            if result.ok:
+                success_count += 1
+                logger.info("    ↳ ✅ Step outcome: Success")
+
+                # PHASE 1 ENHANCEMENT: Capture file content if this was a file creation
+                if step.action in ("file.create", "file.edit"):
+                    params_dict = _params_to_dict(step.params)
+                    file_path = params_dict.get("file_path", "")
+                    if file_path and "code" in params_dict:
+                        files_written[file_path] = params_dict["code"]
+            else:
+                failure_count += 1
+                error_msg = result.data.get("error", "Unknown error")
+                logger.error("    ↳ ❌ Step failed: %s", error_msg)
+
+                # UNIX PHILOSOPHY FIX: Test failures don't block refactoring
+                is_test_step = (
+                    "test" in step.action.lower() or "test" in step.description.lower()
+                )
+
+                if step.is_critical and not is_test_step:
+                    aborted_at_step = i
+                    logger.error("🛑 Critical step failed. Aborting construction.")
+                    break
+                elif is_test_step:
+                    logger.info(
+                        "    ↳ 📋 Test step failed (expected during refactoring) - continuing..."
+                    )
+
+        duration = time.time() - start_time
+
+        logger.info(
+            "🏁 Execution Result: %s (%d success, %d failure) in %.2fs",
+            "✅ CLEAN" if failure_count == 0 else "❌ DIRTY",
+            success_count,
+            failure_count,
+            duration,
+        )
+
+        self.tracer.record(
+            agent="ExecutionAgent",
+            decision_type="plan_execution",
+            rationale=f"Executed blueprint for: {detailed_plan.goal}",
+            chosen_action="Sequential construction",
+            context={
+                "steps": len(results),
+                "success": success_count,
+                "fail": failure_count,
+                "write_mode": self.write,
+                "files_captured": len(files_written),
+            },
+            confidence=1.0 if failure_count == 0 else 0.4,
+        )
+
+        # Build error and warning lists from results
+        errors = []
+        warnings = []
+
+        for result in results:
+            if not result.ok:
+                error_msg = result.data.get("error", "Unknown error")
+                errors.append(error_msg)
+
+            # Extract warnings if present
+            if "warnings" in result.data:
+                warnings.extend(result.data["warnings"])
+
+        # Return simple ExecutionResults matching the dataclass
+        return ExecutionResults(
+            success=failure_count == 0,
+            files_written=list(files_written.keys()),
+            errors=errors,
+            warnings=warnings,
+        )
+
+    # ID: c3d4e5f6-789a-bcde-f012-3456789abcde
+    async def _execute_step(
+        self,
+        step,  # DetailedPlanStep
+        step_number: int,
+    ) -> ActionResult:
+        """
+        Invokes the ActionExecutor for a single atomic action.
+
+        CONSTITUTIONAL NOTE: This is an internal orchestration method, NOT an
+        atomic action. Governance is enforced by ActionExecutor.execute() which
+        issues the governance token for each action it dispatches. Decorating
+        this method with @atomic_action would require a token that doesn't exist
+        at call time, causing GovernanceBypassError.
+        """
+        try:
+            params_dict = _params_to_dict(step.params)
+            params_dict = _strip_params_for_action(step.action, params_dict)
+
+            result = await self.executor.execute(
+                action_id=step.action,
+                write=self.write,
+                **params_dict,
+            )
+
+            return result
+
+        except Exception as e:
+            logger.error("Execution Exception in step %d: %s", step_number, e)
+            return ActionResult(
+                action_id=step.action,
+                ok=False,
+                data={
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+                duration_sec=0.0,
+            )

will/agents/governance_mixin.py

@@ -0,0 +1,132 @@
+# src/will/agents/governance_mixin.py
+
+"""
+Governance Mixin for AI Agents.
+
+Provides constitutional validation for all autonomous operations. This mixin
+allows any agent in the Will layer to check governance before executing actions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from body.services.constitutional_validator import (
+    ApprovalType,
+    GovernanceDecision,
+    RiskTier,
+    can_execute_autonomously,
+)
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+@dataclass
+# ID: 373bbf3b-d13e-468d-813b-5fb8de77bb59
+class GovernanceContext:
+    """Context information for governance decisions."""
+
+    filepath: str
+    action: str
+    agent_id: str
+    additional_context: dict[str, Any] | None = None
+
+
+# ID: dd255352-e203-47e2-9e33-d19cf4317e62
+class GovernanceMixin:
+    """
+    Mixin that adds constitutional governance to any agent.
+
+    Usage:
+        class MyAgent(GovernanceMixin):
+            async def do_something(self, filepath: str):
+                decision = await self.check_governance(
+                    filepath, "modify_file"
+                )
+                if not decision.allowed:
+                    return f"Blocked: {decision.rationale}"
+                # ... proceed with action
+    """
+
+    # ID: e97f31ce-2c86-4b11-b271-68bd8208d7d1
+    async def check_governance(
+        self,
+        filepath: str,
+        action: str,
+        agent_id: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> GovernanceDecision:
+        """
+        Check if action is allowed by constitutional governance.
+
+        Args:
+            filepath: Target file path
+            action: Action to perform
+            agent_id: Identifier of the agent requesting action
+            context: Additional context for governance decision
+
+        Returns:
+            GovernanceDecision with allowed/rationale/violations
+        """
+        gov_context = context or {}
+        gov_context["filepath"] = filepath
+        if agent_id:
+            gov_context["agent_id"] = agent_id
+        decision = can_execute_autonomously(filepath, action, gov_context)
+        self._log_governance_decision(filepath, action, decision)
+        return decision
+
+    def _log_governance_decision(
+        self, filepath: str, action: str, decision: GovernanceDecision
+    ):
+        """Log governance decision for audit trail."""
+        if decision.allowed:
+            logger.info(
+                "✅ Governance: %s on %s",
+                action,
+                filepath,
+                extra={
+                    "governance_decision": "allowed",
+                    "risk_tier": decision.risk_tier.name,
+                    "approval_type": decision.approval_type.value,
+                    "filepath": filepath,
+                    "action": action,
+                },
+            )
+        else:
+            logger.warning(
+                "🚫 Governance: %s on %s - BLOCKED",
+                action,
+                filepath,
+                extra={
+                    "governance_decision": "blocked",
+                    "risk_tier": decision.risk_tier.name,
+                    "filepath": filepath,
+                    "action": action,
+                    "violations": decision.violations,
+                    "rationale": decision.rationale,
+                },
+            )
+
+    # ID: e6c46fa0-3a89-4354-892d-9be7ae047e68
+    def format_governance_response(self, decision: GovernanceDecision) -> str:
+        """Format governance decision for user display."""
+        if decision.allowed:
+            if decision.approval_type == ApprovalType.AUTONOMOUS:
+                return "✅ Action approved for autonomous execution"
+            elif decision.approval_type == ApprovalType.VALIDATION_ONLY:
+                return "✅ Action approved (will validate after execution)"
+        emoji = "⚠️" if decision.risk_tier == RiskTier.ELEVATED else "🚫"
+        msg = f"{emoji} Action blocked by constitutional governance\n"
+        msg += f"   Reason: {decision.rationale}\n"
+        msg += f"   Risk Level: {decision.risk_tier.name}\n"
+        approval_display = decision.approval_type.value.replace("_", " ")
+        msg += f"   Required: {approval_display.title()}"
+        if decision.violations:
+            msg += "\n   Violations:\n"
+            for violation in decision.violations:
+                msg += f"      • {violation}\n"
+        return msg