forgex-cli 0.1.0__py3-none-any.whl

forgex/agents/expert_coder.py

@@ -0,0 +1,283 @@
+"""Expert Coder agent (spec section 10).
+
+A senior reviewer that improves the Builder's work: diff-first context,
+minimal targeted changes, verification through tools.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+
+from forgex.agents.base import BaseAgent, prefetch_files
+from forgex.config.schema import ForgexConfig
+from forgex.models.router import ModelRouter
+from forgex.orchestration.checkpoints import create_checkpoint, find_pre_task_checkpoint
+from forgex.orchestration.events import EventRecorder
+from forgex.orchestration.stores import ProjectStores
+from forgex.research.citations import format_notes
+from forgex.sandbox.permissions import permission_set_for
+from forgex.schemas.agent import AgentRole, ExpertCoderResult
+from forgex.schemas.error import ErrorRecord, ForgexError, ProjectError
+from forgex.schemas.event import EventType
+from forgex.schemas.plan import ArchitecturePlan
+from forgex.schemas.research import ResearchNote
+from forgex.schemas.task import Task
+from forgex.tools import ToolExecutor, build_tool_registry, create_context
+from forgex.tools.git import git_changed_files, git_diff, git_diff_range, is_dirty
+
+logger = logging.getLogger("forgex.agents.expert_coder")
+
+MAX_DIFF_CHARS = 20_000
+MAX_PREFETCH_CHARS = 40_000
+MAX_PREFETCH_FILES = 12
+
+
+class ExpertCoderAgent(BaseAgent):
+    role = AgentRole.EXPERT_CODER
+    prompt_name = "expert_coder"
+
+    def __init__(
+        self,
+        *,
+        router: ModelRouter,
+        tools: ToolExecutor,
+        events: EventRecorder | None = None,
+        run_id: str | None = None,
+    ) -> None:
+        super().__init__(router=router, events=events, run_id=run_id)
+        self._tools = tools
+
+    async def review(
+        self,
+        *,
+        task: Task | None = None,
+        plan: ArchitecturePlan | None = None,
+        research: list[ResearchNote] | None = None,
+        diff: str = "",
+        changed_files: list[str] | None = None,
+        errors: list[ErrorRecord] | None = None,
+        extra_context: str = "",
+    ) -> ExpertCoderResult:
+        if self._events:
+            self._events.record(
+                EventType.AGENT_STARTED,
+                {"agent": self.role.value, "task": task.id if task else None},
+                run_id=self._run_id,
+            )
+
+        changed = list(changed_files or [])
+        seeds = list(changed)
+        try:
+            from forgex.context.manager import ContextManager
+
+            manager = ContextManager(self._tools.context.workspace)
+            for s in changed:
+                for imp in manager.importers_of(s, max_depth=1):
+                    if imp not in seeds:
+                        seeds.append(imp)
+            seeds = seeds[:MAX_PREFETCH_FILES]
+        except Exception:
+            logger.warning("impact analysis unavailable; changed files only", exc_info=True)
+
+        existing = prefetch_files(
+            self._tools.context.workspace,
+            seeds,
+            budget=MAX_PREFETCH_CHARS,
+            max_files=MAX_PREFETCH_FILES,
+        )
+
+        parts: list[str] = []
+        if task:
+            parts.append(
+                f"<task>\nID: {task.id}\nDescription: {task.description}\nCriteria: {', '.join(task.acceptance_criteria)}\n</task>"
+            )
+        if plan:
+            parts.append(f"<plan>\nGoal: {plan.goal}\nArchitecture: {plan.architecture}\n</plan>")
+        if research:
+            parts.append(f"<research>\n{format_notes(research)}\n</research>")
+        if errors:
+            err_text = "\n".join(f"- [{e.source}] {e.kind}: {e.message}" for e in errors[-5:])
+            parts.append(f"<errors>\n{err_text}\n</errors>")
+        if extra_context:
+            parts.append(extra_context)
+
+        diff_snippet = diff[:MAX_DIFF_CHARS] + ("\n... [diff trimmed]" if len(diff) > MAX_DIFF_CHARS else "")
+        parts.append(f"<diff>\n{diff_snippet or '(no diff)'}\n</diff>")
+        if existing:
+            parts.append(f"<existing_files>\n{existing}\n</existing_files>")
+
+        parts.append(
+            "Review the changes above. Refactor, optimize, fix, simplify, and verify with tests. If the code is already solid, change nothing."
+        )
+
+        instruction = "\n\n".join(parts)
+        loop_res = await self._tool_loop(instruction, self._tools, ExpertCoderResult)
+        result: ExpertCoderResult = loop_res.report
+
+        if self._events:
+            self._events.record(
+                EventType.AGENT_COMPLETED,
+                {
+                    "agent": self.role.value,
+                    "status": result.status,
+                    "improvements": len(result.improvements),
+                    "changed_files": result.changed_files,
+                },
+                run_id=self._run_id,
+            )
+        return result
+
+
+def build_coder(
+    *,
+    config: ForgexConfig,
+    workspace: Path,
+    stores: ProjectStores,
+    router: ModelRouter | None = None,
+    approval: Callable[[str], bool] | None = None,
+    run_id: str | None = None,
+) -> ExpertCoderAgent:
+    router = router or ModelRouter(config, usage=stores.usage)
+    tool_ctx = create_context(
+        workspace=workspace,
+        config=config,
+        events=stores.recorder,
+        approval=approval,
+        run_id=run_id,
+        agent=AgentRole.EXPERT_CODER,
+    )
+    tools = ToolExecutor(
+        registry=build_tool_registry(),
+        permissions=permission_set_for(AgentRole.EXPERT_CODER),
+        context=tool_ctx,
+    )
+    return ExpertCoderAgent(
+        router=router,
+        tools=tools,
+        events=stores.recorder,
+        run_id=run_id,
+    )
+
+
+def resolve_review_scope(
+    *,
+    stores: ProjectStores,
+    task_id: str | None,
+    base_commit: str | None,
+) -> tuple[Task | None, str, list[str]] | None:
+    task = None
+    if task_id is not None:
+        tasks = stores.tasks.load()
+        task = next((t for t in tasks if t.id == task_id), None)
+        if task is None:
+            raise ProjectError(f"Unknown task: {task_id}")
+
+    if base_commit is None and task_id is not None and not is_dirty(stores.root):
+        record = find_pre_task_checkpoint(task_id, stores=stores)
+        if record is not None and record.git_commit:
+            base_commit = record.git_commit
+
+    if base_commit:
+        diff = git_diff_range(stores.root, base_commit)
+        changed = git_changed_files(stores.root, base_commit)
+    else:
+        diff = git_diff(stores.root)
+        changed = git_changed_files(stores.root)
+
+    if not diff and not changed:
+        return None
+    return task, diff, changed
+
+
+async def _single_review(
+    *,
+    stores: ProjectStores,
+    config: ForgexConfig,
+    task_id: str | None = None,
+    base_commit: str | None = None,
+    coder: ExpertCoderAgent | None = None,
+    approval: Callable[[str], bool] | None = None,
+) -> ExpertCoderResult | None:
+    state = stores.state.load()
+    if state is None:
+        raise ProjectError("Project state missing — run `forgex init` first.")
+
+    scope = resolve_review_scope(stores=stores, task_id=task_id, base_commit=base_commit)
+    if scope is None:
+        return None
+    task, diff, changed = scope
+
+    create_checkpoint(
+        f"pre-review{'-' + task_id if task_id else ''}",
+        stores=stores,
+        description="Before expert coder review",
+    )
+
+    agent = coder or build_coder(
+        config=config,
+        workspace=stores.root,
+        stores=stores,
+        approval=approval,
+        run_id=state.current_run_id,
+    )
+    owns_agent = coder is None
+    try:
+        result = await agent.review(
+            task=task,
+            plan=state.architecture_plan,
+            research=state.research,
+            diff=diff,
+            changed_files=changed,
+            errors=state.errors[-5:],
+        )
+    except ForgexError as exc:
+        state.errors.append(
+            ErrorRecord(
+                source="expert_coder",
+                kind=type(exc).__name__,
+                message=str(exc),
+                run_id=state.current_run_id,
+            )
+        )
+        stores.save_state(state)
+        raise
+    finally:
+        if owns_agent:
+            await agent.aclose()
+
+    if result.changed_files:
+        state.changed_files = sorted(set(state.changed_files) | set(result.changed_files))
+        stores.save_state(state)
+    return result
+
+
+async def review_work(
+    *,
+    stores: ProjectStores,
+    config: ForgexConfig,
+    task_id: str | None = None,
+    base_commit: str | None = None,
+    coder: ExpertCoderAgent | None = None,
+    approval: Callable[[str], bool] | None = None,
+) -> ExpertCoderResult | None:
+    if config.ensemble.enabled:
+        from forgex.agents.ensemble import ensemble_review
+
+        return await ensemble_review(
+            stores=stores,
+            config=config,
+            task_id=task_id,
+            base_commit=base_commit,
+            applier=coder,
+            approval=approval,
+        )
+    return await _single_review(
+        stores=stores,
+        config=config,
+        task_id=task_id,
+        base_commit=base_commit,
+        coder=coder,
+        approval=approval,
+    )

forgex/agents/supervisor.py

@@ -0,0 +1,303 @@
+"""Supervisor agent (spec sections 11, 56, 58).
+
+inspect → diagnose → instruct repair.
+Verification is deterministic; this agent adds audit judgment;
+quality gates enforce that red tests/builds never pass.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+
+from forgex.agents.base import BaseAgent
+from forgex.config.schema import ForgexConfig
+from forgex.models.router import ModelRouter
+from forgex.orchestration.events import EventRecorder
+from forgex.orchestration.stores import ProjectStores
+from forgex.research.citations import format_notes
+from forgex.sandbox.executor import make_executor
+from forgex.sandbox.permissions import permission_set_for
+from forgex.schemas.agent import (
+    AgentRole,
+    SupervisorJudgment,
+    SupervisorReport,
+)
+from forgex.schemas.error import ErrorRecord, ProjectError
+from forgex.schemas.event import EventType
+from forgex.schemas.plan import ArchitecturePlan
+from forgex.schemas.research import ResearchNote
+from forgex.schemas.result import VerificationOutcome
+from forgex.schemas.task import Task
+from forgex.tools import ToolExecutor, build_tool_registry, create_context
+from forgex.tools.git import current_branch, git_log, has_git_repo, is_dirty
+from forgex.tools.verification import run_verification
+
+logger = logging.getLogger("forgex.agents.supervisor")
+
+
+def _git_summary(root: Path) -> str:
+    if not has_git_repo(root):
+        return "not a git repository"
+    branch = current_branch(root) or "unknown"
+    dirty = "dirty" if is_dirty(root) else "clean"
+    log = git_log(root, limit=5)
+    return f"Branch: {branch} ({dirty})\nRecent commits:\n{log}"
+
+
+def _format_verification(outcome: VerificationOutcome) -> str:
+    lines = []
+    if outcome.tests:
+        t = outcome.tests
+        p = t.passed if t.passed is not None else "?"
+        f = t.failed if t.failed is not None else "?"
+        lines.append(f"Tests: exit={t.exit_code}, passed={p}, failed={f}, timed_out={t.timed_out}")
+        if t.output_tail:
+            lines.append(f"--- test tail ---\n{t.output_tail[-1500:]}")
+    else:
+        lines.append("Tests: not detected / not run")
+
+    if outcome.build:
+        b = outcome.build
+        lines.append(f"Build: exit={b.exit_code}, timed_out={b.timed_out}")
+        if not b.ok and b.output_tail:
+            lines.append(f"--- build error ---\n{b.output_tail[-1000:]}")
+
+    if outcome.lint:
+        ln = outcome.lint
+        lines.append(f"Lint: exit={ln.exit_code}")
+        if not ln.ok and ln.output_tail:
+            lines.append(f"--- lint error ---\n{ln.output_tail[-1000:]}")
+
+    return "\n".join(lines)
+
+
+def apply_quality_gates(
+    judgment: SupervisorJudgment, outcome: VerificationOutcome
+) -> SupervisorReport:
+    """Compose final report. Gates can only worsen a verdict, never improve it."""
+    status = judgment.status
+    errors = list(judgment.errors)
+    warnings = list(judgment.warnings)
+    req_changes = list(judgment.required_changes)
+
+    # 1. Hard gates
+    if outcome.tests is not None:
+        if (outcome.tests.exit_code is not None and outcome.tests.exit_code not in (0, 5)) or (
+            outcome.tests.failed and outcome.tests.failed > 0
+        ):
+            status = "fail"
+            msg = f"tests failed ({outcome.tests.failed or 0} failed, exit {outcome.tests.exit_code})"
+            if msg not in errors:
+                errors.append(msg)
+            if not req_changes:
+                req_changes.append("Fix the failing test suite")
+        if outcome.tests.timed_out:
+            status = "fail"
+            if "tests timed out" not in errors:
+                errors.append("tests timed out")
+
+    if outcome.build is not None and not outcome.build.ok:
+        status = "fail"
+        msg = f"build failed (exit {outcome.build.exit_code})"
+        if msg not in errors:
+            errors.append(msg)
+        if not req_changes:
+            req_changes.append("Fix build failures")
+
+    if outcome.lint is not None and not outcome.lint.ok:
+        status = "fail"
+        msg = f"lint failed (exit {outcome.lint.exit_code})"
+        if msg not in errors:
+            errors.append(msg)
+
+    # 2. Soft gates (floor at needs_review)
+    if outcome.tests is None:
+        warnings.append("no test suite detected")
+        if status == "pass":
+            status = "needs_review"
+    elif outcome.tests.exit_code == 5:
+        warnings.append("pytest collected 0 tests")
+        if status == "pass":
+            status = "needs_review"
+    elif outcome.tests.exit_code is None:
+        warnings.append("test command was not executed")
+        if not any("tests failed" in e for e in errors):
+            errors.append("tests failed: command denied")
+        status = "needs_review"
+
+    # 3. Model verdict preservation
+    if judgment.status in ("fail", "needs_review"):
+        status = judgment.status
+
+    return SupervisorReport(
+        status=status,
+        summary=judgment.summary,
+        errors=errors,
+        warnings=warnings,
+        required_changes=req_changes,
+        recommended_changes=judgment.recommended_changes,
+        tests=outcome.tests,
+        build=outcome.build,
+        lint=outcome.lint,
+    )
+
+
+class SupervisorAgent(BaseAgent):
+    role = AgentRole.SUPERVISOR
+    prompt_name = "supervisor"
+
+    def __init__(
+        self,
+        *,
+        router: ModelRouter,
+        tools: ToolExecutor,
+        events: EventRecorder | None = None,
+        run_id: str | None = None,
+    ) -> None:
+        super().__init__(router=router, events=events, run_id=run_id)
+        self._tools = tools
+
+    async def audit(
+        self,
+        *,
+        request: str,
+        plan: ArchitecturePlan | None,
+        tasks: list[Task],
+        verification: VerificationOutcome,
+        research: list[ResearchNote] | None = None,
+        errors: list[ErrorRecord] | None = None,
+    ) -> SupervisorJudgment:
+        if self._events:
+            self._events.record(
+                EventType.AGENT_STARTED,
+                {"agent": self.role.value},
+                run_id=self._run_id,
+            )
+
+        v_text = _format_verification(verification)
+        git_text = _git_summary(self._tools.context.workspace)
+        research_text = format_notes(research or [])
+
+        tasks_summary = "\n".join(
+            f"- [{t.status.value}] {t.id}: {t.description} (attempts: {t.attempts})"
+            for t in tasks
+        )
+        err_text = "\n".join(f"- [{e.source}] {e.kind}: {e.message}" for e in (errors or [])[-5:])
+
+        instruction = (
+            f"<user_request>\n{request}\n</user_request>\n\n"
+            f"<plan>\nGoal: {plan.goal if plan else 'none'}\nCriteria: {', '.join(plan.acceptance_criteria) if plan else 'none'}\n</plan>\n\n"
+            f"<tasks>\n{tasks_summary}\n</tasks>\n\n"
+            f"<verification>\n{v_text}\n</verification>\n\n"
+            f"<git>\n{git_text}\n</git>\n\n"
+            f"<research>\n{research_text}\n</research>\n\n"
+            f"<errors>\n{err_text or '(no errors recorded)'}\n</errors>\n\n"
+            "Audit the repository. Use tools to inspect code if needed. Return your decisive verdict (pass/fail/needs_review)."
+        )
+
+        loop_res = await self._tool_loop(instruction, self._tools, SupervisorJudgment)
+        result: SupervisorJudgment = loop_res.report
+
+        if self._events:
+            self._events.record(
+                EventType.AGENT_COMPLETED,
+                {
+                    "agent": self.role.value,
+                    "status": result.status,
+                    "errors": len(result.errors),
+                    "required_changes": len(result.required_changes),
+                },
+                run_id=self._run_id,
+            )
+        return result
+
+
+def build_supervisor(
+    *,
+    config: ForgexConfig,
+    workspace: Path,
+    stores: ProjectStores,
+    router: ModelRouter | None = None,
+    approval: Callable[[str], bool] | None = None,
+    run_id: str | None = None,
+) -> SupervisorAgent:
+    router = router or ModelRouter(config, usage=stores.usage)
+    tool_ctx = create_context(
+        workspace=workspace,
+        config=config,
+        events=stores.recorder,
+        approval=approval,
+        run_id=run_id,
+        agent=AgentRole.SUPERVISOR,
+    )
+    tools = ToolExecutor(
+        registry=build_tool_registry(),
+        permissions=permission_set_for(AgentRole.SUPERVISOR),
+        context=tool_ctx,
+    )
+    return SupervisorAgent(
+        router=router,
+        tools=tools,
+        events=stores.recorder,
+        run_id=run_id,
+    )
+
+
+async def supervise(
+    *,
+    stores: ProjectStores,
+    config: ForgexConfig,
+    approval: Callable[[str], bool] | None = None,
+    include_build: bool = True,
+    include_lint: bool = True,
+    supervisor: SupervisorAgent | None = None,
+) -> SupervisorReport:
+    state = stores.state.load()
+    if state is None:
+        raise ProjectError("Project state missing — run `forgex init` first.")
+
+    agent = supervisor or build_supervisor(
+        config=config,
+        workspace=stores.root,
+        stores=stores,
+        approval=approval,
+        run_id=state.current_run_id,
+    )
+    owns_agent = supervisor is None
+
+    exec_inst = getattr(getattr(getattr(agent, "_tools", None), "context", None), "executor", None)
+    if exec_inst is None:
+        exec_inst = make_executor(stores.root, approval=approval)
+
+    outcome = await run_verification(
+        root=stores.root,
+        executor=exec_inst,
+        events=stores.recorder,
+        run_id=state.current_run_id,
+        include_build=include_build,
+        include_lint=include_lint,
+    )
+
+    try:
+        judgment = await agent.audit(
+            request=state.user_request or "",
+            plan=state.architecture_plan,
+            tasks=stores.tasks.load(),
+            verification=outcome,
+            research=state.research,
+            errors=state.errors,
+        )
+    finally:
+        if owns_agent:
+            await agent.aclose()
+
+    report = apply_quality_gates(judgment, outcome)
+
+    state.test_results = outcome.tests
+    state.build_results = outcome.build
+    state.last_supervisor_status = report.status
+    stores.save_state(state)
+
+    return report

forgex/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""