ltcai 9.9.2 → 9.9.4

package/latticeai/api/chat_agent_http.py

@@ -9,15 +9,21 @@ import re
 import secrets
 import threading
 import time
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 
 from lattice_brain.runtime.hooks import dispatch_tool
 from latticeai.api.chat_contracts import AgentEvalRequest, AgentRequest, AgentResumeRequest
 from latticeai.api.chat_helpers import _LANG_HINT, detect_language, workspace_scope_from_request
-from latticeai.core.agent import AgentRunContext, AgentState
+from latticeai.core.agent import AgentRunContext, AgentState, normalize_plan
+from latticeai.core.run_store import (
+    AgentRunStore,
+    hash_approval_token,
+    restore_run_context,
+)
 from latticeai.services.tool_dispatch import collect_artifacts, collect_created_files
 
 
@@ -40,6 +46,8 @@ class AgentHTTPController:
         base_dir: Path,
         agent_root: Path,
         ensure_agent_root: Any,
+        funnel_metrics: Any = None,
+        run_store: Any = None,
     ) -> None:
         self.runtime = runtime
         self.model_router = model_router
@@ -56,9 +64,26 @@ class AgentHTTPController:
         self.base_dir = Path(base_dir)
         self.agent_root = Path(agent_root)
         self.ensure_agent_root = ensure_agent_root
+        self.funnel_metrics = funnel_metrics
         self._pending: Dict[str, tuple] = {}
         self._pending_lock = threading.Lock()
         self._pending_ttl_seconds = 15 * 60
+        # awaiting_approval runs: run_id -> paused run state + approval token.
+        # Fail-closed: governed steps only ever execute after resume presents
+        # the matching, unexpired token for this run (or via the legacy
+        # explicit human-in-loop context flow above).
+        self._approvals: Dict[str, Dict[str, Any]] = {}
+        self._approval_ttl_seconds = 10 * 60
+        # Durable side of the approval loop (review Wave 0.1): paused runs are
+        # mirrored to disk so a valid token still resumes after a restart or
+        # from another worker process. In-memory stays the fast path.
+        self.run_store = run_store if run_store is not None else AgentRunStore(
+            Path(base_dir) / "data" / "agent_runs"
+        )
+        try:
+            self.run_store.sweep_expired()
+        except Exception as exc:  # noqa: BLE001 — hygiene must not break startup
+            logging.warning("agent run store sweep failed: %s", exc)
         self._background_tasks: set[asyncio.Task] = set()
 
     def register_routes(self, router: APIRouter) -> None:
@@ -74,6 +99,10 @@ class AgentHTTPController:
         async def agent_resume(req: AgentResumeRequest, request: Request):
             return await self.resume(req, request)
 
+        @router.get("/agent/approvals")
+        async def agent_approvals(request: Request):
+            return self.pending_approvals(request)
+
     def _schedule_background_task(self, coro: Any) -> None:
         task = asyncio.create_task(coro)
         self._background_tasks.add(task)
@@ -171,8 +200,17 @@ class AgentHTTPController:
             "results": results,
         }
 
-    async def agent(self, req: AgentRequest, request: Request) -> Dict[str, Any]:
-        """Plan and execute a natural-language local agent run."""
+    async def agent(
+        self,
+        req: AgentRequest,
+        request: Request,
+        on_step: Any = None,
+    ) -> Dict[str, Any]:
+        """Plan and execute a natural-language local agent run.
+
+        ``on_step`` (optional) is a per-run step observer — the live SSE
+        route attaches one so the client sees progress while EXECUTING.
+        """
         current_user = self.require_user(request)
         self.enforce_rate_limit(current_user, "agent")
         effective_email = self.authenticated_identity(current_user, req.user_email)
@@ -198,6 +236,8 @@ class AgentHTTPController:
         max_steps = max(1, min(req.max_steps, 50))
         max_retry = 3
         ctx = AgentRunContext()
+        if on_step is not None:
+            ctx.on_step = on_step
         ctx.executing_model = req.executing_model
         ctx.reviewing_model = req.reviewing_model
         ctx.state = AgentState.PLANNING
@@ -232,6 +272,18 @@ class AgentHTTPController:
                 "loop": ctx.trace.summary(),
             }
 
+        # Interactive approval: when the plan needs human approval, pause the
+        # run as awaiting_approval (short-TTL token) instead of failing it.
+        # ``getattr`` keeps injected fake runtimes without the preview method
+        # on the historical fail-closed path.
+        requirements_probe = getattr(self.runtime, "approval_requirements", None)
+        if callable(requirements_probe):
+            requirements = requirements_probe(ctx)
+            if requirements.get("requires_approval"):
+                return self._pause_for_approval(
+                    ctx, req, language_hint, current_user, requirements,
+                )
+
         self.runtime.approve(ctx, current_user, approved_by_human=False)
         return await self._finish(
             ctx,
@@ -242,6 +294,177 @@ class AgentHTTPController:
             max_retry,
         )
 
+    def _pause_for_approval(
+        self,
+        ctx: AgentRunContext,
+        req: AgentRequest,
+        language_hint: str,
+        current_user: str,
+        requirements: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Park a plan that needs approval and hand the user a resume token."""
+        run_id = secrets.token_urlsafe(16)
+        approval_token = secrets.token_urlsafe(32)
+        now_monotonic = time.monotonic()
+        expires_at = (
+            datetime.now(timezone.utc) + timedelta(seconds=self._approval_ttl_seconds)
+        ).isoformat(timespec="seconds")
+        with self._pending_lock:
+            self._purge_expired_approvals_locked(now_monotonic)
+            self._approvals[run_id] = {
+                "ctx": ctx,
+                "req": req,
+                "language_hint": language_hint,
+                "user": current_user,
+                "token": approval_token,
+                "expires_monotonic": now_monotonic + self._approval_ttl_seconds,
+                "expires_at": expires_at,
+            }
+        # Durable mirror: a restart between pause and resume must not orphan
+        # the run. Best-effort — the in-memory pause still answers on failure.
+        try:
+            self.run_store.save(
+                run_id,
+                ctx=ctx,
+                req_payload=req.model_dump(),
+                language_hint=language_hint,
+                user=current_user,
+                token=approval_token,
+                expires_epoch=time.time() + self._approval_ttl_seconds,
+                expires_at=expires_at,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logging.warning("agent run store persist failed: %s", exc)
+        if self.funnel_metrics is not None:
+            try:
+                self.funnel_metrics.increment("approval_pauses")
+            except Exception as exc:  # noqa: BLE001 — advisory only
+                logging.warning("funnel metrics increment failed: %s", exc)
+        ctx.state_history.append(AgentState.WAITING_APPROVAL.value)
+        message = (
+            "이 작업에는 승인이 필요한 단계가 있어 실행을 잠시 멈췄습니다. "
+            "계획을 확인한 뒤 승인하면 이어서 실행합니다."
+        )
+        return {
+            "status": "awaiting_approval",
+            "run_id": run_id,
+            "approval": {
+                "token": approval_token,
+                "expires_at": expires_at,
+                "plan_summary": requirements.get("plan_summary", ""),
+            },
+            "response": message,
+            "plan": ctx.plan,
+            "steps": ctx.transcript,
+            "state_history": ctx.state_history,
+            "final_state": AgentState.WAITING_APPROVAL.value,
+            "non_auto_steps": requirements.get("non_auto_steps", []),
+            "planning_model": req.planning_model or self.model_router.current_model_id,
+            "executing_model": req.executing_model or self.model_router.current_model_id,
+            "reviewing_model": req.reviewing_model or self.model_router.current_model_id,
+            "loop": ctx.trace.summary(),
+        }
+
+    def _purge_expired_approvals_locked(self, now_monotonic: float) -> None:
+        for run_id, entry in list(self._approvals.items()):
+            if now_monotonic >= entry["expires_monotonic"]:
+                self._approvals.pop(run_id, None)
+                try:
+                    self.run_store.delete(run_id)
+                except Exception:  # noqa: BLE001 — hygiene only
+                    pass
+
+    def pending_approvals(self, request: Request) -> Dict[str, Any]:
+        """Unexpired paused runs for the current user (memory ∪ disk).
+
+        Lets the UI re-surface an approval card after a reload/restart instead
+        of the run silently vanishing.
+        """
+        current_user = self.require_user(request)
+        now_monotonic = time.monotonic()
+        pending: Dict[str, Dict[str, Any]] = {}
+        with self._pending_lock:
+            for run_id, entry in self._approvals.items():
+                if entry["user"] != current_user:
+                    continue
+                if now_monotonic >= entry["expires_monotonic"]:
+                    continue
+                plan = getattr(entry["ctx"], "plan", {}) or {}
+                pending[run_id] = {
+                    "run_id": run_id,
+                    "goal": str(plan.get("goal") or "")[:200],
+                    "expires_at": entry["expires_at"],
+                }
+        try:
+            for summary in self.run_store.pending_summaries(current_user):
+                run_id = summary.get("run_id")
+                if run_id and run_id not in pending:
+                    pending[run_id] = {
+                        "run_id": run_id,
+                        "goal": summary.get("goal") or "",
+                        "expires_at": summary.get("expires_at"),
+                    }
+        except Exception as exc:  # noqa: BLE001 — disk listing is best-effort
+            logging.warning("agent run store listing failed: %s", exc)
+        return {"pending": sorted(pending.values(), key=lambda p: p["run_id"])}
+
+    def _restore_persisted_approval(self, run_id: str) -> Optional[Dict[str, Any]]:
+        """Rebuild an approval entry from disk after a restart.
+
+        Returns an entry shaped like the in-memory ones but carrying
+        ``token_hash`` instead of the plaintext token. Expired records are
+        deleted and reported via the same 410 contract as the memory path.
+        """
+        try:
+            record = self.run_store.load(run_id)
+        except Exception as exc:  # noqa: BLE001 — load error == not found
+            logging.warning("agent run store load failed: %s", exc)
+            return None
+        if record is None:
+            return None
+        req_payload = record.get("req") or {}
+        if time.time() >= float(record.get("expires_epoch") or 0):
+            try:
+                self.run_store.delete(run_id)
+            except Exception:  # noqa: BLE001
+                pass
+            raise HTTPException(
+                status_code=410,
+                detail={
+                    "error": "approval_expired",
+                    "message": "Approval token expired. Start a new request.",
+                    "replan": {"message": str(req_payload.get("message") or "")},
+                },
+            )
+        try:
+            restored_req = AgentRequest(**req_payload)
+        except Exception as exc:  # noqa: BLE001 — unreconstructable == not found
+            logging.warning("agent run store request restore failed: %s", exc)
+            return None
+        remaining = max(1.0, float(record["expires_epoch"]) - time.time())
+        return {
+            "ctx": restore_run_context(record.get("ctx") or {}),
+            "req": restored_req,
+            "language_hint": str(record.get("language_hint") or "English"),
+            "user": record.get("user"),
+            "token_hash": str(record.get("token_hash") or ""),
+            "expires_monotonic": time.monotonic() + remaining,
+            "expires_at": record.get("expires_at"),
+        }
+
+    @staticmethod
+    def _token_matches(entry: Dict[str, Any], supplied: str) -> bool:
+        """Constant-time token check for both plaintext and hashed entries."""
+        if not supplied:
+            return False
+        stored = entry.get("token")
+        if stored is not None:
+            return secrets.compare_digest(str(stored), supplied)
+        stored_hash = str(entry.get("token_hash") or "")
+        return bool(stored_hash) and secrets.compare_digest(
+            stored_hash, hash_approval_token(supplied)
+        )
+
     async def _finish(
         self,
         ctx: AgentRunContext,
@@ -299,6 +522,16 @@ class AgentHTTPController:
             )
         except Exception as exc:
             logging.warning("workspace agent run record failed: %s", exc)
+        if self.funnel_metrics is not None:
+            # UX funnel (backlog #16): every completed agent run counts, and
+            # NEEDS_REVIEW terminals feed the needs_review_rate the review
+            # gates watch. Advisory only — a metrics failure never fails chat.
+            try:
+                self.funnel_metrics.increment("agent_runs")
+                if ctx.state == AgentState.NEEDS_REVIEW:
+                    self.funnel_metrics.increment("needs_review_runs")
+            except Exception as exc:  # noqa: BLE001
+                logging.warning("funnel metrics increment failed: %s", exc)
         return {
             "status": "ok" if ctx.state == AgentState.DONE else "failed",
             "response": message,
@@ -316,8 +549,22 @@ class AgentHTTPController:
         req: AgentResumeRequest,
         request: Request,
     ) -> Dict[str, Any]:
-        """Resume a paused agent after human approval of the plan."""
+        """Resume a paused agent after human approval of the plan.
+
+        Two entry modes share this endpoint:
+
+        * ``run_id`` + ``approval_token`` — an ``awaiting_approval`` run
+          (token-validated, short TTL, bound to the pausing user);
+        * ``context_id`` — the legacy explicit human-in-loop pause.
+        """
         current_user = self.require_user(request)
+        if req.run_id:
+            return await self._resume_approval(req, current_user)
+        if not req.context_id:
+            raise HTTPException(
+                status_code=400,
+                detail="run_id (with approval_token) or context_id is required.",
+            )
         with self._pending_lock:
             now = time.monotonic()
             for context_id, pending in list(self._pending.items()):
@@ -345,7 +592,117 @@ class AgentHTTPController:
             ctx.transcript[-1].update(ctx.plan)
         ctx.executing_model = req.executing_model or ctx.executing_model
         ctx.reviewing_model = req.reviewing_model or ctx.reviewing_model
-        self.runtime.approve(ctx, current_user)
+        # The authenticated owner of this pending context explicitly approved
+        # the plan — record it as a human approval so approval-gated steps can
+        # actually run instead of terminating the run as FAILED.
+        self.runtime.approve(ctx, current_user, approved_by_human=True)
+        return await self._finish(
+            ctx,
+            original_request,
+            language_hint,
+            current_user,
+            max(1, min(original_request.max_steps, 50)),
+            3,
+        )
+
+    async def _resume_approval(
+        self,
+        req: AgentResumeRequest,
+        current_user: str,
+    ) -> Dict[str, Any]:
+        """Validate an awaiting_approval token, then continue or cancel the run."""
+        now_monotonic = time.monotonic()
+        with self._pending_lock:
+            entry = self._approvals.get(req.run_id or "")
+            if entry is None:
+                # Restart survival (review Wave 0.1): the in-memory dict is
+                # gone but the durable record may still be valid.
+                entry = self._restore_persisted_approval(req.run_id or "")
+            if entry is None:
+                raise HTTPException(
+                    status_code=404,
+                    detail="Agent run not found. It may have expired — start a new request.",
+                )
+            if entry["user"] != current_user:
+                raise HTTPException(
+                    status_code=403,
+                    detail="Agent run belongs to another user.",
+                )
+            if now_monotonic >= entry["expires_monotonic"]:
+                self._approvals.pop(req.run_id, None)
+                try:
+                    self.run_store.delete(req.run_id or "")
+                except Exception:  # noqa: BLE001
+                    pass
+                raise HTTPException(
+                    status_code=410,
+                    detail={
+                        "error": "approval_expired",
+                        "message": "Approval token expired. Start a new request.",
+                        "replan": {"message": getattr(entry.get("req"), "message", "")},
+                    },
+                )
+            if not self._token_matches(entry, req.approval_token or ""):
+                raise HTTPException(
+                    status_code=403,
+                    detail="Invalid approval token for this run.",
+                )
+            # Token validated — the pending run is consumed either way.
+            self._approvals.pop(req.run_id, None)
+            try:
+                self.run_store.delete(req.run_id or "")
+            except Exception as exc:  # noqa: BLE001 — consumption must proceed
+                logging.warning("agent run store delete failed: %s", exc)
+            self._purge_expired_approvals_locked(now_monotonic)
+
+        ctx: AgentRunContext = entry["ctx"]
+        original_request: AgentRequest = entry["req"]
+        language_hint: str = entry["language_hint"]
+
+        if self.funnel_metrics is not None:
+            # approval_resume_rate = resumes / pauses (review §4.3): counted on
+            # every token-valid resume decision, approve and deny alike.
+            try:
+                self.funnel_metrics.increment("approval_resumes")
+            except Exception as exc:  # noqa: BLE001 — advisory only
+                logging.warning("funnel metrics increment failed: %s", exc)
+
+        approved = req.approve if req.approve is not None else req.approved
+        if not approved:
+            message = "사용자가 계획을 취소했습니다."
+            try:
+                self.workspace_store.record_agent_run(
+                    agent_id="agent:executor",
+                    status="cancelled",
+                    input_text=original_request.message,
+                    output_text=message,
+                    user_email=current_user or None,
+                    workspace_id=original_request.workspace_id,
+                    mode="llm",
+                    timeline=ctx.transcript,
+                    relationships=["agent:planner", "agent:reviewer"],
+                    graph=self.workspace_graph(),
+                )
+            except Exception as exc:
+                logging.warning("workspace agent run record failed: %s", exc)
+            return {
+                "status": "cancelled",
+                "run_id": req.run_id,
+                "response": message,
+            }
+
+        edited_plan = req.edited_plan or req.modified_plan
+        if edited_plan:
+            plan, plan_fixes = normalize_plan(edited_plan, original_request.message)
+            ctx.plan = plan
+            ctx.transcript.append({
+                "state": AgentState.WAITING_APPROVAL.value,
+                "edited_plan": True,
+                **({"plan_fixes": plan_fixes} if plan_fixes else {}),
+            })
+        ctx.executing_model = req.executing_model or ctx.executing_model
+        ctx.reviewing_model = req.reviewing_model or ctx.reviewing_model
+        self.runtime.approve(ctx, current_user, approved_by_human=True)
         return await self._finish(
             ctx,
             original_request,

package/latticeai/api/chat_contracts.py

@@ -39,11 +39,17 @@ class AgentRequest(BaseModel):
 
 
 class AgentResumeRequest(BaseModel):
-    context_id: str
+    # Legacy human-in-loop pause (kept working): context_id + approved.
+    context_id: Optional[str] = None
     approved: bool = True
     modified_plan: Optional[dict] = None
     executing_model: Optional[str] = None
     reviewing_model: Optional[str] = None
+    # awaiting_approval flow (v9.10): run_id + short-TTL approval token.
+    run_id: Optional[str] = None
+    approval_token: Optional[str] = None
+    approve: Optional[bool] = None
+    edited_plan: Optional[dict] = None
 
 
 class AgentEvalRequest(BaseModel):

package/latticeai/api/chat_helpers.py

@@ -245,6 +245,153 @@ def build_context_quality(
     return context_quality_signal("lexical_only", len(matches))
 
 
+# ── answer-citation binding (backlog #11, review §7.2 E #4) ──────────────────
+_GROUNDING_TOKEN_RE = re.compile(r"[0-9A-Za-z가-힣]{2,}")
+# High-frequency tokens that overlap by accident, not by grounding.
+_GROUNDING_STOP_TOKENS = frozenset({
+    "그리고", "그러나", "하지만", "그래서", "있습니다", "입니다", "합니다",
+    "있는", "없는", "위해", "통해", "대한", "관련", "경우", "내용", "answer",
+    "the", "and", "for", "with", "this", "that", "from", "have", "are",
+    "was", "were", "can", "will", "not", "you", "your",
+})
+GROUNDING_MIN_OVERLAP_TOKENS = 2
+GROUNDING_MIN_OVERLAP_RATIO = 0.08
+
+
+def _grounding_tokens(text: str) -> set:
+    return {
+        token.lower()
+        for token in _GROUNDING_TOKEN_RE.findall(str(text or ""))
+        if token.lower() not in _GROUNDING_STOP_TOKENS
+    }
+
+
+def assess_answer_grounding(
+    answer: str,
+    *,
+    trace: Optional[Dict[str, object]] = None,
+    context_quality: Optional[Dict[str, object]] = None,
+) -> Dict[str, object]:
+    """Bind an answer to its retrieved sources — honestly (never blocks).
+
+    Heuristic: for each retrieved source (the answer trace's ``graph_nodes``
+    / ``source_files``), measure content-token overlap between the answer and
+    the source's title+summary, and accept explicit citations (the answer
+    names the source title or filename). Returns::
+
+        {"status": "supported",   "label": "근거 있음", "source_ids": [...],
+         "cited": [...], "overlap": float}
+        {"status": "unsupported", "label": "근거 없음", "source_ids": [], ...}
+        {"status": "no_context",  "label": "근거 없음", ...}  # nothing retrieved
+
+    ``no_context`` (still labeled 근거 없음) lets the UI distinguish "the
+    Brain had nothing" from "the Brain had sources but the answer ignored
+    them". Annotation only — the answer is never modified or blocked.
+    """
+    answer_text = str(answer or "").strip()
+    trace = trace if isinstance(trace, dict) else {}
+    sources: List[Dict[str, object]] = []
+    seen_ids = set()
+    for node in list(trace.get("graph_nodes") or []):
+        if not isinstance(node, dict):
+            continue
+        node_id = str(node.get("id") or node.get("node_id") or "")
+        if not node_id or node_id in seen_ids:
+            continue
+        seen_ids.add(node_id)
+        meta = node.get("metadata") if isinstance(node.get("metadata"), dict) else {}
+        sources.append({
+            "id": node_id,
+            "title": str(node.get("title") or ""),
+            "body": " ".join(
+                str(part or "")
+                for part in (node.get("title"), node.get("summary"), meta.get("filename"))
+            ),
+        })
+    for src in list(trace.get("source_files") or []):
+        if not isinstance(src, dict):
+            continue
+        node_id = str(src.get("node_id") or src.get("source") or "")
+        if not node_id or node_id in seen_ids:
+            continue
+        seen_ids.add(node_id)
+        sources.append({
+            "id": node_id,
+            "title": str(src.get("node_title") or ""),
+            "body": " ".join(
+                str(part or "") for part in (src.get("node_title"), src.get("source"))
+            ),
+        })
+
+    mode = str((context_quality or {}).get("mode") or "none")
+    if not sources:
+        return {
+            "status": "no_context",
+            "label": "근거 없음",
+            "source_ids": [],
+            "cited": [],
+            "overlap": 0.0,
+            "reason": (
+                "검색된 출처가 없습니다"
+                if mode == "none"
+                else "출처 후보를 답변에 연결하지 못했습니다"
+            ),
+        }
+    if not answer_text:
+        return {
+            "status": "unsupported",
+            "label": "근거 없음",
+            "source_ids": [],
+            "cited": [],
+            "overlap": 0.0,
+            "reason": "답변이 비어 있습니다",
+        }
+
+    answer_tokens = _grounding_tokens(answer_text)
+    answer_lower = answer_text.lower()
+    cited: List[Dict[str, object]] = []
+    best_overlap = 0.0
+    for source in sources:
+        source_tokens = _grounding_tokens(source["body"])
+        if not source_tokens:
+            continue
+        shared = answer_tokens & source_tokens
+        denominator = max(1, min(len(source_tokens), 60))
+        ratio = len(shared) / denominator
+        best_overlap = max(best_overlap, ratio)
+        title = str(source.get("title") or "").strip().lower()
+        explicit = bool(title) and len(title) >= 4 and title in answer_lower
+        # Explicit-citation OR token-overlap binding. Comparisons are explicit
+        # (a 0.0 score is falsy but a valid value — never use `or` defaults).
+        if explicit or (
+            len(shared) >= GROUNDING_MIN_OVERLAP_TOKENS
+            and ratio >= GROUNDING_MIN_OVERLAP_RATIO
+        ):
+            cited.append({
+                "id": source["id"],
+                "title": source.get("title"),
+                "overlap": round(ratio, 4),
+                "explicit": explicit,
+            })
+    if cited:
+        return {
+            "status": "supported",
+            "label": "근거 있음",
+            "source_ids": [item["id"] for item in cited],
+            "cited": cited,
+            "overlap": round(best_overlap, 4),
+            "reason": None,
+        }
+    return {
+        "status": "unsupported",
+        "label": "근거 없음",
+        "source_ids": [],
+        "cited": [],
+        "overlap": round(best_overlap, 4),
+        "reason": "답변이 검색된 출처의 내용을 사용하지 않았습니다",
+    }
+
+
 def workspace_scope_from_request(request: Request) -> Optional[str]:
     header = request.headers.get("X-Workspace-Id")
     if header and header.strip():