core-runtime 0.1.1__py3-none-any.whl

will/agents/strategic_auditor/effects.py

@@ -0,0 +1,136 @@
+# src/will/agents/strategic_auditor/effects.py
+
+"""
+StrategicAuditor — campaign side effects on the world.
+
+Two operations, both gated by StrategicAuditor.run()'s write /
+execute_autonomous flags and both taking a finished StrategicCampaign:
+
+- persist_campaign: write a parent Task plus one child Task per
+  autonomous cluster and one escalation Task per amendment-required
+  cluster, via TaskRepository. Two session commits.
+- execute_autonomous_tasks: iterate the campaign's autonomous clusters,
+  gate on confidence >= 0.7, dispatch each to develop_from_goal.
+
+Both share one reason to change: how a finished campaign acts on the
+system. Splitting them apart would fragment that single answer.
+
+LAYER: will/agents — collaborator of StrategicAuditor. Sessions and
+context flow in from the caller; no service-registry session
+construction here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shared.infrastructure.repositories.task_repository import TaskRepository
+from shared.logger import getLogger
+from will.agents.strategic_auditor.models import StrategicCampaign
+
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from shared.context import CoreContext
+
+
+logger = getLogger(__name__)
+
+
+# ID: f4d82377-ffce-4794-9bc3-754a48eed83d
+async def persist_campaign(session: AsyncSession, campaign: StrategicCampaign) -> None:
+    """Store campaign as parent Task + child Tasks in PostgreSQL."""
+    repo = TaskRepository(session)
+
+    parent = await repo.create(
+        intent=f"[StrategicCampaign:{campaign.campaign_id}] {campaign.system_summary[:200]}",
+        assigned_role="StrategicAuditor",
+        status="campaign_ready",
+    )
+    parent.context = {
+        "campaign_id": campaign.campaign_id,
+        "total_findings": campaign.total_findings,
+        "autonomous_tasks": campaign.autonomous_task_count,
+        "escalations": campaign.escalation_count,
+        "system_summary": campaign.system_summary,
+    }
+    await session.commit()
+
+    for cluster in campaign.clusters:
+        child = await repo.create(
+            intent=cluster.proposed_fix,
+            assigned_role="AutonomousDeveloper",
+            status="pending",
+        )
+        child.parent_task_id = parent.id
+        child.requires_approval = False
+        child.context = {
+            "cluster_id": cluster.cluster_id,
+            "root_cause": cluster.root_cause,
+            "affected_files": cluster.affected_files,
+            "finding_ids": cluster.finding_ids,
+            "confidence": cluster.confidence,
+            "estimated_impact": cluster.estimated_impact,
+        }
+
+    for cluster in campaign.escalations:
+        child = await repo.create(
+            intent=f"[ESCALATION] {cluster.proposed_fix}",
+            assigned_role="Human",
+            status="awaiting_approval",
+        )
+        child.parent_task_id = parent.id
+        child.requires_approval = True
+        child.context = {
+            "cluster_id": cluster.cluster_id,
+            "root_cause": cluster.root_cause,
+            "constitutional_amendment_needed": cluster.proposed_fix,
+            "affected_files": cluster.affected_files,
+        }
+
+    await session.commit()
+    logger.info(
+        "Campaign persisted: parent=%s, %d tasks, %d escalations",
+        parent.id,
+        campaign.autonomous_task_count,
+        campaign.escalation_count,
+    )
+
+
+# ID: b63d2bae-56c3-4f98-80e3-f1c9cc170ca3
+async def execute_autonomous_tasks(
+    ctx: CoreContext, session: AsyncSession, campaign: StrategicCampaign
+) -> None:
+    """Execute non-escalation clusters via develop_from_goal.
+
+    Clusters below the 0.7 confidence threshold are skipped — they remain
+    persisted as pending Tasks for a human to review rather than being
+    autonomously executed.
+    """
+    from will.autonomy.autonomous_developer import develop_from_goal
+
+    logger.info("Executing %d autonomous tasks...", campaign.autonomous_task_count)
+
+    for i, cluster in enumerate(campaign.clusters, 1):
+        logger.info(
+            "  [%d/%d] %s (impact=%s, confidence=%.2f)",
+            i,
+            campaign.autonomous_task_count,
+            cluster.root_cause[:80],
+            cluster.estimated_impact,
+            cluster.confidence,
+        )
+
+        if cluster.confidence < 0.7:
+            logger.info("    Skipping (confidence too low — staged for review)")
+            continue
+
+        success, message = await develop_from_goal(
+            context=ctx,
+            goal=cluster.proposed_fix,
+            workflow_type=cluster.workflow_type,
+            write=True,
+            session=session,
+        )
+        logger.info("    %s %s", "OK" if success else "FAIL", message)

will/agents/strategic_auditor/models.py

@@ -0,0 +1,61 @@
+# src/will/agents/strategic_auditor/models.py
+
+"""
+Data structures for the StrategicAuditor campaign.
+
+Pure data — no logic, no imports from CORE internals.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+# ID: 2ebdd1a6-3c94-4b49-8d61-00f8ed2ba976
+class RootCauseCluster:
+    """
+    A group of audit findings that share a single root cause.
+
+    The LLM produces these — they are the core reasoning unit of the campaign.
+    """
+
+    cluster_id: str
+    root_cause: str
+    """Single sentence: why do all these findings exist?"""
+
+    affected_files: list[str]
+    finding_ids: list[str]
+    proposed_fix: str
+    """Concrete, actionable description of what needs to change."""
+
+    requires_constitution_change: bool = False
+    """True → escalate to human. False → CORE can fix autonomously."""
+
+    confidence: float = 0.8
+    estimated_impact: str = "medium"
+    """low / medium / high — how much does fixing this improve CORE?"""
+
+
+@dataclass
+# ID: 75de5708-f567-46e4-a350-bfadc21c6e19
+class StrategicCampaign:
+    """
+    The full output of a StrategicAuditor run.
+
+    Stored as a parent Task in PostgreSQL with child Tasks per cluster.
+    """
+
+    campaign_id: str
+    created_at: datetime
+    system_summary: str
+    """LLM's one-paragraph assessment of CORE's current state."""
+
+    clusters: list[RootCauseCluster] = field(default_factory=list)
+    escalations: list[RootCauseCluster] = field(default_factory=list)
+    """Clusters that require human (.intent/) amendment."""
+
+    total_findings: int = 0
+    autonomous_task_count: int = 0
+    escalation_count: int = 0

will/agents/strategic_auditor/reasoning.py

@@ -0,0 +1,169 @@
+# src/will/agents/strategic_auditor/reasoning.py
+
+"""
+StrategicAuditor — campaign synthesis.
+
+The LLM contract layer for StrategicAuditor. Takes a system_context dict
+gathered by SystemContextGatherer and produces a StrategicCampaign by:
+
+1. Compacting findings into a per-rule summary (token-budget aware).
+2. Invoking the architect_threats_analysis_prompt PromptModel.
+3. Parsing the JSON response (fenced-block tolerant).
+4. Constructing RootCauseCluster instances and partitioning them into
+   autonomous-vs-escalation buckets per requires_constitution_change.
+
+Fail-soft: on any LLM/parse error the function returns a campaign with an
+empty cluster list and a diagnostic system_summary so the caller's
+downstream effects (persist, execute, log) still have something coherent
+to operate on.
+
+LAYER: will/agents — collaborator of StrategicAuditor. No DB writes, no
+file writes, no .intent/ access. The only side effect is the LLM call.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from shared.ai.prompt_model import PromptModel
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+from will.agents.strategic_auditor.models import RootCauseCluster, StrategicCampaign
+
+
+if TYPE_CHECKING:
+    from will.orchestration.cognitive_service import CognitiveService
+
+
+logger = getLogger(__name__)
+
+_CFG_SA = load_operational_config().strategic_auditor
+
+_VALID_WORKFLOW_TYPES = frozenset(
+    {
+        "refactor_modularity",
+        "coverage_remediation",
+        "full_feature_development",
+    }
+)
+
+
+def _resolve_workflow_type(value: str) -> str:
+    """Return value if it is a known workflow type, else the safe default."""
+    if isinstance(value, str) and value.strip() in _VALID_WORKFLOW_TYPES:
+        return value.strip()
+    logger.warning(
+        "Unknown or missing workflow_type '%s' from LLM — "
+        "defaulting to full_feature_development",
+        value,
+    )
+    return "full_feature_development"
+
+
+# ID: b1f24560-023b-4482-819a-169708c7130f
+async def synthesize_campaign(
+    cognitive: CognitiveService,
+    system_context: dict[str, Any],
+) -> StrategicCampaign:
+    """Send system context to the LLM and parse the strategic campaign.
+
+    The prompt name (architect_threats_analysis_prompt) and the expected
+    response schema (clusters list with root_cause / proposed_fix /
+    requires_constitution_change / workflow_type / confidence / impact)
+    are the LLM contract this function owns.
+    """
+    findings = system_context.get("audit_findings", [])
+
+    findings_by_rule: dict[str, list[str]] = {}
+    for f in findings:
+        rid = f.get("rule_id", "unknown")
+        ffile = f.get("file", "unknown")
+        findings_by_rule.setdefault(rid, []).append(ffile)
+
+    lines = []
+    for rid, files in sorted(findings_by_rule.items()):
+        unique = sorted(set(files))[:5]
+        suffix = f" (+{len(files) - 5} more)" if len(files) > 5 else ""
+        lines.append(
+            f"  [{rid}] in {len(files)} locations: {', '.join(unique)}{suffix}"
+        )
+
+    def _compact(obj: Any, max_chars: int = _CFG_SA.compact_max_chars) -> str:
+        s = json.dumps(obj, indent=2, default=str)
+        return s[:max_chars] + "..." if len(s) > max_chars else s
+
+    logger.info("Reasoning about system state (LLM call)...")
+
+    try:
+        model = PromptModel.load("architect_threats_analysis_prompt")
+        client = await cognitive.aget_client_for_role(model.manifest.role)
+        response = await model.invoke(
+            context={
+                "finding_count": len(findings),
+                "audit_findings_summary": "\n".join(lines[:50]),
+                "semantic_landscape": _compact(
+                    system_context.get("semantic_landscape", {})
+                ),
+                "knowledge_gaps": _compact(system_context.get("knowledge_gaps", {})),
+                "structural_health": _compact(
+                    system_context.get("structural_health", {})
+                ),
+                "change_context": _compact(system_context.get("change_context", {})),
+                "intent_drift": _compact(system_context.get("intent_drift", {})),
+                "constitution_summary": _compact(
+                    {
+                        "policy_count": system_context.get(
+                            "constitution_summary", {}
+                        ).get("policy_count", 0),
+                        "policies": system_context.get("constitution_summary", {}).get(
+                            "policy_ids", []
+                        )[:15],
+                    }
+                ),
+            },
+            client=client,
+            user_id="StrategicAuditor",
+        )
+        raw = response.strip()
+        if raw.startswith("```"):
+            raw = raw.split("```")[1]
+            if raw.startswith("json"):
+                raw = raw[4:]
+        data = json.loads(raw.strip())
+    except Exception as e:
+        logger.error("LLM reasoning failed: %s", e)
+        data = {"system_summary": f"Strategic audit failed: {e}", "clusters": []}
+
+    campaign_id = str(uuid.uuid4())
+    clusters: list[RootCauseCluster] = []
+    escalations: list[RootCauseCluster] = []
+
+    for c in data.get("clusters", []):
+        cluster = RootCauseCluster(
+            cluster_id=c.get("cluster_id", str(uuid.uuid4())[:8]),
+            root_cause=c.get("root_cause", ""),
+            affected_files=c.get("affected_files", []),
+            finding_ids=c.get("finding_ids", []),
+            proposed_fix=c.get("proposed_fix", ""),
+            requires_constitution_change=c.get("requires_constitution_change", False),
+            confidence=float(c.get("confidence", 0.8)),
+            estimated_impact=c.get("estimated_impact", "medium"),
+            workflow_type=_resolve_workflow_type(c.get("workflow_type", "")),
+        )
+        (escalations if cluster.requires_constitution_change else clusters).append(
+            cluster
+        )
+
+    return StrategicCampaign(
+        campaign_id=campaign_id,
+        created_at=datetime.now(UTC),
+        system_summary=data.get("system_summary", ""),
+        clusters=clusters,
+        escalations=escalations,
+        total_findings=len(findings),
+        autonomous_task_count=len(clusters),
+        escalation_count=len(escalations),
+    )

will/agents/tagger_agent.py

@@ -0,0 +1,294 @@
+# src/will/agents/tagger_agent.py
+
+"""
+Implements the CapabilityTaggerAgent, which finds unassigned capabilities
+and uses an LLM to suggest constitutionally-valid names for them.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from shared.ai.prompt_model import PromptModel
+from shared.infrastructure.knowledge.knowledge_service import KnowledgeService
+from shared.logger import getLogger
+from shared.utils.parallel_processor import ThrottledParallelProcessor
+from will.orchestration.cognitive_service import CognitiveService
+from will.orchestration.decision_tracer import DecisionTracer
+
+
+logger = getLogger(__name__)
+
+
+# ID: fa3e820c-ed8c-4785-b94d-4cb5a1ae23b8
+class CapabilityTaggerAgent:
+    """An agent that finds unassigned capabilities and suggests names."""
+
+    def __init__(
+        self,
+        cognitive_service: CognitiveService,
+        knowledge_service: KnowledgeService,
+        entry_point_patterns: list | None = None,
+    ):
+        """Initializes the agent with the tools it needs."""
+        self.cognitive_service = cognitive_service
+        self.knowledge_service = knowledge_service
+        self.tracer = DecisionTracer()
+        self.prompt_model = PromptModel.load("capability_definer")
+        self.tagger_client = None
+        self.entry_point_patterns = entry_point_patterns or []
+
+    def _is_entry_point(self, symbol_data: dict[str, Any]) -> bool:
+        """
+        Checks if a symbol matches any of the defined entry point patterns.
+        Copied directly from OrphanedLogicCheck.
+        """
+        for pattern in self.entry_point_patterns:
+            match_rules = pattern.get("match", {})
+            if not match_rules:
+                continue
+            is_a_match = all(
+                self._evaluate_match_rule(rule_key, rule_value, symbol_data)
+                for rule_key, rule_value in match_rules.items()
+            )
+            if is_a_match:
+                return True
+        return False
+
+    def _evaluate_match_rule(self, key: str, value: Any, data: dict) -> bool:
+        """
+        Evaluates a single criterion for the entry point pattern matching.
+        Copied directly from OrphanedLogicCheck.
+        """
+        if key == "type":
+            kind = data.get("type", "")
+            is_function_type = kind in ("function", "method")
+            return (value == "function" and is_function_type) or (value == kind)
+        if key == "name_regex":
+            return bool(re.search(value, data.get("name", "")))
+        if key == "module_path_contains":
+            file_path = data.get("file_path", "")
+            module_path = (
+                file_path.replace("src/", "").replace(".py", "").replace("/", ".")
+            )
+            return value in module_path
+        if key == "is_public_function":
+            return data.get("is_public", False) is value
+        if key == "has_capability_tag":
+            return (data.get("capability") is not None) == value
+        return data.get(key) == value
+
+    def _find_orphaned_symbols(self, all_symbols: list[dict]) -> list[dict]:
+        """
+        Finds truly orphaned symbols using the exact same logic as OrphanedLogicCheck.
+
+        A symbol is orphaned if it is:
+        1. Public
+        2. Has no capability assigned (capability is None)
+        3. Is NOT an entry point
+        4. Is NOT called by any other code
+        """
+        if not all_symbols:
+            return []
+
+        # Build call graph (same as OrphanedLogicCheck)
+        all_called_symbols = set()
+        for symbol_data in all_symbols:
+            called_list = symbol_data.get("calls") or []
+            for called_qualname in called_list:
+                all_called_symbols.add(called_qualname)
+
+        orphaned_symbols = []
+        for symbol_data in all_symbols:
+            is_public = symbol_data.get("is_public", False)
+            has_no_key = symbol_data.get("capability") is None
+
+            if not (is_public and has_no_key):
+                continue
+
+            if self._is_entry_point(symbol_data):
+                continue
+
+            qualname = symbol_data.get("name", "")
+            short_name = qualname.split(".")[-1]
+            is_called = (qualname in all_called_symbols) or (
+                short_name in all_called_symbols
+            )
+
+            if not is_called:
+                orphaned_symbols.append(symbol_data)
+
+        return orphaned_symbols
+
+    async def _get_existing_capabilities(self) -> list[str]:
+        """Fetches existing capabilities asynchronously."""
+        return await self.knowledge_service.list_capabilities()
+
+    def _extract_symbol_info(self, symbol: dict[str, Any]) -> dict[str, Any]:
+        """Extracts the relevant information for the prompt from a symbol entry."""
+        return {
+            "key": symbol.get("uuid"),
+            "name": symbol.get("name"),
+            "file": symbol.get("file_path"),
+            "domain": symbol.get("domain"),
+            "docstring": symbol.get("docstring"),
+        }
+
+    def _build_prompt_context(
+        self, symbol_info: dict[str, Any], existing_capabilities: list[str]
+    ) -> dict[str, str]:
+        """
+        Builds the PromptModel context dict for a single symbol invocation.
+
+        Returns a dict matching the input contract declared in model.yaml.
+        """
+        similar_caps_text = "\n".join(
+            [f"- {cap}" for cap in existing_capabilities[:20]]
+        )
+
+        code_snippet = f"# {symbol_info.get('name', 'unknown')}\n"
+        if symbol_info.get("docstring"):
+            code_snippet += f'"""{symbol_info["docstring"]}"""\n'
+        code_snippet += f"# Domain: {symbol_info.get('domain', 'unknown')}\n"
+        code_snippet += f"# File: {symbol_info.get('file', 'unknown')}"
+
+        return {
+            "similar_capabilities": similar_caps_text,
+            "code": code_snippet,
+        }
+
+    @staticmethod
+    def _strip_markdown(response: str) -> str:
+        """Strips markdown code fences from LLM response if present."""
+        clean = response.strip()
+        if clean.startswith("```"):
+            clean = re.sub(r"^```[a-z]*\n?", "", clean)
+            clean = re.sub(r"\n?```$", "", clean.strip())
+        return clean.strip()
+
+    async def _get_suggestion_for_symbol(
+        self, symbol: dict[str, Any], existing_capabilities: list[str]
+    ) -> dict[str, str] | None:
+        """
+        Async worker to get a single tag suggestion from the LLM via PromptModel.
+        """
+        symbol_info = self._extract_symbol_info(symbol)
+        context = self._build_prompt_context(symbol_info, existing_capabilities)
+
+        try:
+            response = await self.prompt_model.invoke(
+                context,
+                client=self.tagger_client,
+                user_id="tagger_agent",
+            )
+            parsed = json.loads(self._strip_markdown(response))
+            suggestion = parsed.get("suggested_capability")
+
+            # DECISION TRACING: record the LLM-driven capability suggestion.
+            # Satisfies autonomy.tracing.mandatory by recording the agent's
+            # core decision — what capability name to suggest for an
+            # orphaned symbol — at the point the LLM response is parsed.
+            self.tracer.record(
+                agent="CapabilityTaggerAgent",
+                decision_type="capability_suggestion",
+                rationale=(
+                    f"LLM produced suggestion for orphaned symbol "
+                    f"{symbol.get('name')!r} in {symbol_info.get('file')!r}"
+                ),
+                chosen_action=(
+                    f"Suggest capability: {suggestion!r}"
+                    if suggestion
+                    else "Reject — LLM returned no suggestion"
+                ),
+                alternatives=existing_capabilities[:5],
+                context={
+                    "symbol_uuid": symbol.get("uuid"),
+                    "symbol_name": symbol.get("name"),
+                    "file": symbol_info.get("file"),
+                    "domain": symbol_info.get("domain"),
+                },
+                confidence=0.8 if suggestion else 0.0,
+            )
+
+            if not suggestion:
+                return None
+            return {
+                "key": symbol.get("uuid"),
+                "name": symbol.get("name"),
+                "file": symbol_info.get("file"),
+                "line_number": symbol.get("line_number", 1),
+                "suggestion": suggestion,
+            }
+        except (json.JSONDecodeError, AttributeError, ValueError):
+            logger.warning("Could not parse suggestion for %s.", symbol.get("name"))
+        return None
+
+    # ID: 02466161-a46e-4fc2-8011-ddd05ada4d1c
+    async def suggest_and_apply_tags(
+        self,
+        file_path: Path | None = None,
+        limit: int = 0,
+    ) -> dict[str, dict] | None:
+        """
+        Finds truly orphaned public symbols (using OrphanedLogicCheck logic),
+        gets AI-powered suggestions via PromptModel, and returns them.
+
+        Args:
+            file_path: Optional path to filter symbols by file.
+            limit: Max number of symbols to process (0 = all).
+
+        Returns:
+            Dict mapping symbol keys to suggestion dicts, or None if no suggestions.
+        """
+        if self.tagger_client is None:
+            self.tagger_client = await self.cognitive_service.aget_client_for_role(
+                self.prompt_model.manifest.role
+            )
+
+        logger.info("Searching for orphaned capabilities (using audit logic)...")
+
+        existing_capabilities = await self._get_existing_capabilities()
+        graph = await self.knowledge_service.get_graph()
+        all_symbols = list(graph.get("symbols", {}).values())
+
+        orphaned_symbols = self._find_orphaned_symbols(all_symbols)
+
+        if file_path:
+            orphaned_symbols = [
+                s
+                for s in orphaned_symbols
+                if s.get("file_path", "").endswith(str(file_path))
+            ]
+
+        if limit > 0:
+            orphaned_symbols = orphaned_symbols[:limit]
+
+        logger.info(
+            "Found %d truly orphaned symbols (same as audit).", len(orphaned_symbols)
+        )
+
+        if not orphaned_symbols:
+            return None
+
+        logger.info(
+            "Analyzing %d orphaned symbols for capability suggestions...",
+            len(orphaned_symbols),
+        )
+
+        processor = ThrottledParallelProcessor(description="Tagging capabilities...")
+
+        # ID: 00304bca-a84a-499c-b6ce-124cf6c24ad9
+        async def worker_fn(symbol: dict) -> dict | None:
+            return await self._get_suggestion_for_symbol(symbol, existing_capabilities)
+
+        results = await processor.run_async(
+            items=orphaned_symbols,
+            worker_fn=worker_fn,
+        )
+
+        suggestions = {r["key"]: r for r in results if r is not None}
+
+        return suggestions or None

will/agents/traced_agent_mixin.py

@@ -0,0 +1,33 @@
+# src/will/agents/traced_agent_mixin.py
+"""TracedAgentMixin - Shared decision trace interface.
+
+Eliminates AST duplication between ExecutionAgent and SpecificationAgent.
+Both hold self.tracer = DecisionTracer() and expose identical get_decision_trace
+and save_decision_trace methods.
+
+Usage:
+    # ID: c9a742bb-eb84-4a3a-86a2-a5f1faeeaa38
+    class MyAgent(TracedAgentMixin):
+        def __init__(self):
+            self.tracer = DecisionTracer()
+"""
+
+from __future__ import annotations
+
+
+# ID: d2e3f4a5-b6c7-8901-defa-123456789012
+class TracedAgentMixin:
+    """Mixin for Will agents that own a DecisionTracer instance.
+
+    Requires subclass to set self.tracer = DecisionTracer() in __init__.
+    """
+
+    # ID: e3f4a5b6-c7d8-9012-efab-234567890123
+    def get_decision_trace(self) -> str:
+        """Return formatted decision trace from this agent's tracer."""
+        return self.tracer.format_trace()
+
+    # ID: f4a5b6c7-d8e9-0123-fabc-345678901234
+    async def save_decision_trace(self) -> None:
+        """Persist the decision trace to disk via the tracer."""
+        await self.tracer.save_trace()