feat(runtime): añade AgentOrchestrator (invoke + resume HITL + snapshot)

Punto único de entrada al runtime. Cada llamada abre su propio AsyncSqliteSaver
sobre data_dir/checkpoints.sqlite, así que un awaiting_approval sobrevive a un
reinicio del proceso (verificado en test_estado_persiste_entre_instancias).
El plan no incluía tests del orchestrator; se añaden 5 (invoke feliz, pausa HITL +
resume aprobar/rechazar, bloqueo por guardrail, persistencia entre instancias).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

core/src/agentforge_core/runtime/orchestrator.py

@@ -0,0 +1,164 @@
+"""Orchestrator: envuelve build_graph + ainvoke/resume + serialización a ``AgentExecution``.
+
+Es el único punto de entrada al runtime: el router de FastAPI lo usa para lanzar
+ejecuciones y reanudar pausas Human-in-the-Loop. Cada llamada abre su propio
+``AsyncSqliteSaver`` (context manager) sobre ``data_dir/checkpoints.sqlite``, así que
+el estado de un ``awaiting_approval`` sobrevive a un reinicio del proceso: basta crear
+otro ``AgentOrchestrator`` apuntando al mismo ``data_dir`` y llamar a ``resume``.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID, uuid4
+
+import structlog
+from langgraph.types import Command
+
+from agentforge_core.domain.agent import AgentDefinition
+from agentforge_core.domain.execution import AgentExecution, DecisionStep, ProposedAction
+from agentforge_core.domain.guardrail import GuardrailViolation
+from agentforge_core.domain.policy import PolicyDefinition
+from agentforge_core.guardrails.base import GuardrailEngine
+from agentforge_core.llm.base import LLMProvider
+from agentforge_core.runtime.checkpointer import build_checkpointer
+from agentforge_core.runtime.graph import build_graph
+
+log = structlog.get_logger(__name__)
+
+_TERMINAL_STATUSES = frozenset({"completed", "failed", "blocked_by_guardrail"})
+
+
+def _thread_config(trace_id: UUID) -> dict[str, Any]:
+    return {"configurable": {"thread_id": str(trace_id)}}
+
+
+class AgentOrchestrator:
+    """Punto único de entrada para invocar agentes y reanudar pausas HITL."""
+
+    def __init__(
+        self, *, provider: LLMProvider, engine: GuardrailEngine, data_dir: Path
+    ) -> None:
+        self._provider = provider
+        self._engine = engine
+        self._data_dir = data_dir
+
+    async def invoke(
+        self,
+        *,
+        agent_def: AgentDefinition,
+        policy: PolicyDefinition,
+        user_input: str,
+        trace_id: UUID | None = None,
+    ) -> AgentExecution:
+        """Lanza una ejecución. Si hay acciones que requieren aprobación, devuelve
+        ``status="awaiting_approval"`` y el grafo queda pausado en el checkpointer."""
+        tid = trace_id or uuid4()
+        started_at = datetime.now(UTC)
+        initial: dict[str, Any] = {
+            "trace_id": str(tid),
+            "agent_name": agent_def.name,
+            "agent_version": agent_def.version,
+            "user_input": user_input,
+            "messages": [],
+            "raw_llm_output": None,
+            "parsed_output": None,
+            "proposed_actions": [],
+            "violations": [],
+            "decision_path": [],
+            "status": "running",
+            "error": None,
+            "human_decision": None,
+            "final_output": None,
+        }
+        async with build_checkpointer(self._data_dir) as checkpointer:
+            graph = build_graph(
+                agent_def=agent_def,
+                policy=policy,
+                provider=self._provider,
+                engine=self._engine,
+                checkpointer=checkpointer,
+            )
+            crashed = False
+            try:
+                await graph.ainvoke(initial, config=_thread_config(tid))
+            except Exception:
+                log.exception("agent_invoke_failed", trace_id=str(tid))
+                crashed = True
+            return await self._snapshot(graph, agent_def, tid, started_at, crashed=crashed)
+
+    async def resume(
+        self,
+        *,
+        agent_def: AgentDefinition,
+        policy: PolicyDefinition,
+        trace_id: UUID,
+        decision: dict[str, Any],
+    ) -> AgentExecution:
+        """Reanuda una ejecución pausada en HITL con la decisión del operador."""
+        started_at = datetime.now(UTC)
+        async with build_checkpointer(self._data_dir) as checkpointer:
+            graph = build_graph(
+                agent_def=agent_def,
+                policy=policy,
+                provider=self._provider,
+                engine=self._engine,
+                checkpointer=checkpointer,
+            )
+            crashed = False
+            try:
+                await graph.ainvoke(Command(resume=decision), config=_thread_config(trace_id))
+            except Exception:
+                log.exception("agent_resume_failed", trace_id=str(trace_id))
+                crashed = True
+            return await self._snapshot(graph, agent_def, trace_id, started_at, crashed=crashed)
+
+    async def _snapshot(
+        self,
+        graph: Any,
+        agent_def: AgentDefinition,
+        trace_id: UUID,
+        started_at: datetime,
+        *,
+        crashed: bool,
+    ) -> AgentExecution:
+        """Lee el estado del checkpointer y lo serializa a ``AgentExecution``."""
+        state = await graph.aget_state(_thread_config(trace_id))
+        values: dict[str, Any] = state.values or {}
+        status: str = values.get("status", "running")
+        if crashed and status not in _TERMINAL_STATUSES:
+            status = "failed"
+        elif state.next and status not in _TERMINAL_STATUSES:
+            # LangGraph reporta nodos pendientes → pausado en interrupt() (approve_gate).
+            status = "awaiting_approval"
+
+        proposed = [ProposedAction.model_validate(a) for a in values.get("proposed_actions", [])]
+        violations = [GuardrailViolation.model_validate(v) for v in values.get("violations", [])]
+        decision_path = [DecisionStep.model_validate(s) for s in values.get("decision_path", [])]
+        needs_human = (
+            [
+                a
+                for a in proposed
+                if a.risk_score >= agent_def.risk_threshold_for_hitl or a.requires_approval
+            ]
+            if status == "awaiting_approval"
+            else None
+        )
+        error = values.get("error") or ("internal_error" if crashed else None)
+        finished_at = datetime.now(UTC) if status in _TERMINAL_STATUSES else None
+        return AgentExecution(
+            trace_id=trace_id,
+            agent_name=agent_def.name,
+            agent_version=agent_def.version,
+            status=status,
+            started_at=started_at,
+            finished_at=finished_at,
+            decision_path=decision_path,
+            violations=violations,
+            proposed_actions=proposed,
+            needs_human_for=needs_human,
+            final_output=values.get("final_output"),
+            error=error,
+        )