ltcai 9.9.2 → 9.9.3

package/latticeai/api/browser.py

@@ -27,7 +27,7 @@ from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
 from latticeai import __version__
-from lattice_brain.ingestion import IngestionItem
+from lattice_brain.ingestion import IngestionItem, capture_quality_verdict
 
 MAX_TAB_BYTES = 4 * 1024 * 1024          # 4 MB per captured tab payload
 MAX_URL_FETCH_BYTES = 4 * 1024 * 1024    # 4 MB cap on a fetched page
@@ -427,7 +427,10 @@ def create_browser_router(
             raise HTTPException(status_code=422, detail=str(exc))
         if not (text or "").strip():
             return {"status": "empty", "source_type": "web_url", "url": url,
-                    "detail": "No readable text was extracted from the page."}
+                    "detail": "No readable text was extracted from the page.",
+                    # Structured CTA (backlog #9): the extraction produced
+                    # nothing, tell the UI what the user can do about it.
+                    "capture_quality": capture_quality_verdict(None, source_type="web_url")}
         res = pipeline.ingest(
             IngestionItem(
                 source_type="web_url", title=title, text=text, source_uri=url,
@@ -435,7 +438,11 @@ def create_browser_router(
             ),
             user_email=user,
         )
-        return res.as_dict()
+        payload = res.as_dict()
+        payload["capture_quality"] = capture_quality_verdict(
+            res.extraction_quality, source_type="web_url",
+        )
+        return payload
 
     @router.post("/api/browser/ingest-current-tab")
     async def ingest_current_tab(req: IngestTabRequest, request: Request):
@@ -481,6 +488,10 @@ def create_browser_router(
             ),
             user_email=user,
         )
-        return res.as_dict()
+        payload = res.as_dict()
+        payload["capture_quality"] = capture_quality_verdict(
+            res.extraction_quality, source_type="browser_tab",
+        )
+        return payload
 
     return router

package/latticeai/api/chat.py

@@ -28,6 +28,7 @@ from latticeai.api.chat_documents import (
 )
 from latticeai.api.chat_helpers import (
     _LANG_HINT,
+    assess_answer_grounding,
     build_context_quality,
     build_recent_chat_context,
     detect_language,
@@ -189,6 +190,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
         base_dir=context.base_dir or Path.cwd(),
         agent_root=AGENT_ROOT,
         ensure_agent_root=ensure_agent_root,
+        funnel_metrics=context.funnel_metrics,
     )
     intent_controller = ChatIntentController(
         model_router=model_router,
@@ -209,6 +211,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
         agent_controller=agent_controller,
         agent_root=AGENT_ROOT,
         ingestion_pipeline=context.ingestion_pipeline,
+        funnel_metrics=context.funnel_metrics,
     )
     document_coordinator = DocumentGenerationCoordinator(
         model_router=model_router,
@@ -273,7 +276,12 @@ def create_chat_router(context: AppContext) -> APIRouter:
             )
 
         selected_model_id = request_model(req.model)
-        if is_file_action_request(req.message):
+        file_intent = is_file_action_request(req.message)
+        if file_intent and context.funnel_metrics is not None:
+            # UX funnel (backlog #16): one file-intent request counted once,
+            # regardless of which delivery path handles it below.
+            context.funnel_metrics.increment("file_requests")
+        if file_intent:
             direct_response = await intent_controller.direct_file_action(
                 req,
                 model_id=selected_model_id,
@@ -284,7 +292,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
                 return direct_response
         if not selected_model_id:
             return intent_controller.no_model_response()
-        if is_file_action_request(req.message):
+        if file_intent:
             return await intent_controller.route_file_to_agent(
                 req,
                 request,
@@ -375,6 +383,12 @@ def create_chat_router(context: AppContext) -> APIRouter:
         )
         if isinstance(trace_seed, dict):
             trace_seed["context_quality"] = context_quality
+        if context.funnel_metrics is not None and int(
+            context_quality.get("nodes") or 0
+        ) > 0:
+            # UX funnel (backlog #16): a grounded answer is "first value" —
+            # the TTFV clock ends on the first successful recall.
+            context.funnel_metrics.record_recall_success()
 
         history_message = (
             f"{req.message}\n[Image attached]" if req.image_data else req.message
@@ -464,6 +478,16 @@ def create_chat_router(context: AppContext) -> APIRouter:
             req.image_data,
         )
         response_text = str(result)
+        # Answer-citation binding (backlog #11): annotate — never block — how
+        # the answer relates to the retrieved sources. Recorded on the trace
+        # so the Review/proof surfaces see the same verdict as the client.
+        grounding = assess_answer_grounding(
+            response_text,
+            trace=trace_seed if isinstance(trace_seed, dict) else None,
+            context_quality=context_quality,
+        )
+        if isinstance(trace_seed, dict):
+            trace_seed["grounding"] = grounding
         trace_record = await chat_service.persist_answer(
             question=req.message,
             response=response_text,
@@ -482,6 +506,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
                 "trace_id": trace_record["id"],
                 "trace": trace_record,
                 "context_quality": context_quality,
+                "grounding": grounding,
             }
         )
 

package/latticeai/api/chat_agent_http.py

@@ -9,6 +9,7 @@ import re
 import secrets
 import threading
 import time
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict
 
@@ -17,7 +18,7 @@ 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.services.tool_dispatch import collect_artifacts, collect_created_files
 
 
@@ -40,6 +41,7 @@ class AgentHTTPController:
         base_dir: Path,
         agent_root: Path,
         ensure_agent_root: Any,
+        funnel_metrics: Any = None,
     ) -> None:
         self.runtime = runtime
         self.model_router = model_router
@@ -56,9 +58,16 @@ 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
         self._background_tasks: set[asyncio.Task] = set()
 
     def register_routes(self, router: APIRouter) -> None:
@@ -232,6 +241,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 +263,62 @@ 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,
+            }
+        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)
+
     async def _finish(
         self,
         ctx: AgentRunContext,
@@ -299,6 +376,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 +403,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 +446,94 @@ 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:
+                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)
+                raise HTTPException(
+                    status_code=410,
+                    detail="Approval token expired. Start a new request.",
+                )
+            supplied = req.approval_token or ""
+            if not supplied or not secrets.compare_digest(entry["token"], supplied):
+                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)
+            self._purge_expired_approvals_locked(now_monotonic)
+
+        ctx: AgentRunContext = entry["ctx"]
+        original_request: AgentRequest = entry["req"]
+        language_hint: str = entry["language_hint"]
+
+        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():