ltcai 9.9.5 → 10.0.0

package/latticeai/integrations/telegram_bot.py

@@ -36,6 +36,7 @@ STATUS_URL     = f"{BASE_URL}/status"
 MODELS_URL     = f"{BASE_URL}/models"
 GRAPH_STATS_URL = f"{BASE_URL}/knowledge-graph/stats"
 UPLOAD_DOC_URL  = f"{BASE_URL}/upload/document"
+PROPOSALS_URL   = f"{BASE_URL}/api/proposals"
 
 AGENT_RESUME_URL      = f"{BASE_URL}/agent/resume"
 AGENT_WORKSPACE       = Path(env_value("LATTICEAI_AGENT_ROOT", "agent_workspace")).resolve()
@@ -297,6 +298,9 @@ MAIN_MENU = {
             {"text": "🔗 웹 UI 열기",           "callback_data": "cmd:web"},
             {"text": "🔌 MCP 도구 목록",        "callback_data": "cmd:mcp"},
         ],
+        [
+            {"text": "🗂 변경 제안 검토",        "callback_data": "cmd:review"},
+        ],
     ]
 }
 
@@ -665,6 +669,176 @@ def collect_generated_files(agent_data):
             files.append((path, target))
     return files
 
+def format_grounding_badge(data, *, language: str = "ko") -> str:
+    """Answer-grounding badge line for a `/chat` reply (v9.9.7).
+
+    Telegram used to show only the answer text, so a reply the Brain could not
+    ground looked identical to one built on real sources. This renders exactly
+    the verdict the server issued — and reports an absent verdict as unknown
+    rather than promoting it to "근거 있음".
+    """
+    if not isinstance(data, dict):
+        return ""
+    grounding = data.get("grounding")
+    if not isinstance(grounding, dict):
+        return ""
+    status = str(grounding.get("status") or "")
+    if not status:
+        return ""
+    korean = not str(language or "ko").startswith("en")
+    cited = [
+        str(item.get("title") or "").strip()
+        for item in (grounding.get("cited") or [])
+        if isinstance(item, dict) and str(item.get("title") or "").strip()
+    ]
+    if status == "supported":
+        head = "✅ 근거 있음" if korean else "✅ grounded"
+        if cited:
+            head += " — " + ", ".join(cited[:3])
+        return head
+    if status in {"unsupported", "no_context"}:
+        head = "⚠️ 근거 없음" if korean else "⚠️ not grounded"
+        reason = str(grounding.get("reason") or "").strip()
+        return f"{head} — {reason}" if reason else head
+    return "❔ 근거 확인 불가" if korean else "❔ grounding unknown"
+
+
+async def send_grounding_badge(client, chat_id, data):
+    text = format_grounding_badge(data)
+    if text:
+        await send_message(client, chat_id, text)
+
+
+def format_proposals(payload) -> list:
+    """`GET /api/proposals` → ``[(item_id, label)]`` for the Review Center.
+
+    Rows without an id are dropped: an un-actionable row is worse than none.
+    """
+    root = payload if isinstance(payload, dict) else {}
+    rows = payload if isinstance(payload, list) else (root.get("items") or [])
+    out = []
+    for raw in rows if isinstance(rows, list) else []:
+        if not isinstance(raw, dict):
+            continue
+        item_id = str(raw.get("id") or "").strip()
+        if not item_id:
+            continue
+        body = raw.get("payload") if isinstance(raw.get("payload"), dict) else {}
+        provenance = raw.get("provenance") if isinstance(raw.get("provenance"), dict) else {}
+        path = str(body.get("path") or provenance.get("path") or "")
+        title = str(raw.get("title") or path or item_id)
+        change_class = str(body.get("change_class") or provenance.get("change_class") or "")
+        label = title if not change_class else f"{title} ({change_class})"
+        out.append((item_id, label))
+    return out
+
+
+async def show_review_center(client, chat_id):
+    """Review Center parity (v9.9.7): staged change proposals with inline
+    approve/reject, using the same `/api/proposals` surface as the web app."""
+    try:
+        async with _server_client() as sc:
+            res = await sc.get(PROPOSALS_URL, timeout=30.0)
+        if res.status_code != 200:
+            await send_message(client, chat_id, f"검토함을 불러오지 못했습니다 ({res.status_code})")
+            return
+        items = format_proposals(res.json())
+    except Exception as exc:
+        await send_message(client, chat_id, f"검토함 조회 실패: {exc}")
+        return
+    if not items:
+        await send_message(client, chat_id, "🗂 검토할 변경 제안이 없습니다.")
+        return
+    lines = ["🗂 변경 제안 (승인해야 적용됩니다)"]
+    keyboard = []
+    for item_id, label in items[:8]:
+        lines.append(f"- {label}")
+        keyboard.append([
+            {"text": f"✅ 승인 — {label}"[:64], "callback_data": f"proposal:approve:{item_id}"[:64]},
+            {"text": "❌ 거절"[:64], "callback_data": f"proposal:reject:{item_id}"[:64]},
+        ])
+    if len(items) > 8:
+        lines.append(f"… 외 {len(items) - 8}건")
+    await send_message(
+        client, chat_id, "\n".join(lines),
+        reply_markup={"inline_keyboard": keyboard},
+    )
+
+
+async def handle_proposal_callback(client, chat_id, data: str):
+    """Apply or reject one staged proposal.
+
+    A 409 means the target file changed since staging — nothing was written,
+    and the user is told exactly that instead of a silent retry.
+    """
+    try:
+        _, decision, item_id = data.split(":", 2)
+    except ValueError:
+        return
+    if not item_id:
+        return
+    suffix = "approve" if decision == "approve" else "reject"
+    url = f"{PROPOSALS_URL}/{item_id}/{suffix}"
+    try:
+        async with _server_client() as sc:
+            res = await sc.post(url, json={}, timeout=120.0)
+    except Exception as exc:
+        await send_message(client, chat_id, f"❌ 처리 실패: {exc}")
+        return
+    if res.status_code == 409:
+        await send_message(
+            client, chat_id,
+            "⚠️ 제안을 만든 뒤 파일이 바뀌어서 적용하지 않았습니다. 아무것도 쓰지 않았습니다.",
+        )
+        return
+    if res.status_code != 200:
+        await send_message(client, chat_id, f"❌ 서버 에러 ({res.status_code})")
+        return
+    if suffix == "approve":
+        try:
+            applied = res.json().get("path") or item_id
+        except Exception:
+            applied = item_id
+        await send_message(client, chat_id, f"✅ 적용했습니다: {applied}")
+    else:
+        await send_message(client, chat_id, "🚫 제안을 거절했습니다.")
+
+
+def format_run_explanation(agent_data, *, language: str = "ko") -> str:
+    """Plain-language outcome line for a finished agent run (v9.9.6).
+
+    Telegram used to show only the final message, so a NEEDS_REVIEW run read
+    exactly like a success. The server already computes the honest sentence
+    (`explanation`); this renders it. Returns "" when there is nothing to add
+    — a clean, verified run gets no extra noise.
+    """
+    if not isinstance(agent_data, dict):
+        return ""
+    explanation = agent_data.get("explanation")
+    if not isinstance(explanation, dict):
+        return ""
+    lang = "ko" if str(language or "ko").startswith("ko") else "en"
+
+    def pick(entry):
+        return str(entry.get(lang) or "") if isinstance(entry, dict) else ""
+
+    details = [pick(item) for item in explanation.get("details") or []]
+    details = [line for line in details if line]
+    if explanation.get("ok") and not details:
+        return ""
+    headline = pick(explanation.get("headline"))
+    marker = "✅" if explanation.get("ok") else "⚠️"
+    lines = [f"{marker} {headline}" if headline else marker]
+    lines.extend(f"· {line}" for line in details[:4])
+    return "\n".join(lines)
+
+
+async def send_run_explanation(client, chat_id, agent_data):
+    text = format_run_explanation(agent_data)
+    if text:
+        await send_message(client, chat_id, text)
+
+
 def collect_preview_urls(agent_data):
     urls, seen = [], set()
     for step in agent_data.get("steps", []):
@@ -819,6 +993,7 @@ async def handle_plan_callback(client, chat_id, data: str) -> None:
         ans = data_r.get("response", f"❌ 서버 에러 ({res.status_code})")
         await send_message(client, chat_id, str(ans))
         if isinstance(data_r, dict):
+            await send_run_explanation(client, chat_id, data_r)
             await send_generated_files(client, chat_id, collect_generated_files(data_r))
             await send_preview_links(client, chat_id, collect_preview_urls(data_r))
     except Exception as e:
@@ -862,7 +1037,12 @@ async def process_ai_request(client, chat_id, user_text, image_data=None):
         if not ans or not str(ans).strip():
             ans = "⚠️ AI가 답변을 생성하지 못했습니다."
         await send_message(client, chat_id, str(ans))
+        if isinstance(data, dict):
+            # Recall parity (v9.9.7): the same grounding verdict the web app
+            # badges, never promoted when the server issued none.
+            await send_grounding_badge(client, chat_id, data)
         if not image_data and isinstance(data, dict):
+            await send_run_explanation(client, chat_id, data)
             await send_generated_files(client, chat_id, collect_generated_files(data))
             await send_preview_links(client, chat_id, collect_preview_urls(data))
     except Exception as e:
@@ -887,6 +1067,7 @@ HELP_TEXT = """\
 /clear [n] — 기록 정리 (마지막 n건 유지)
 /web — 웹 UI 링크
 /mcp — MCP 도구 목록
+/review — 변경 제안 검토함 (승인/거절)
 /help — 이 도움말
 
 /agent <작업> — 멀티 LLM 에이전트 (계획 확인 후 실행)
@@ -925,6 +1106,8 @@ async def handle_command(client, chat_id, command: str, args: str):
         await send_web_link(client, chat_id)
     elif cmd == "mcp":
         await send_mcp_tools(client, chat_id)
+    elif cmd in {"review", "proposals"}:
+        await show_review_center(client, chat_id)
     elif cmd in {"help", "h"}:
         await send_message(client, chat_id, HELP_TEXT)
     elif cmd == "agent":
@@ -986,6 +1169,8 @@ async def handle_callback_query(client, callback_query):
         await send_web_link(client, chat_id)
     elif data == "cmd:mcp":
         await send_mcp_tools(client, chat_id)
+    elif data == "cmd:review":
+        await show_review_center(client, chat_id)
     elif data == "cmd:menu":
         await show_menu(client, chat_id)
     elif data.startswith("model:unload:"):
@@ -994,6 +1179,9 @@ async def handle_callback_query(client, callback_query):
     elif data.startswith("plan:"):
         task = asyncio.create_task(handle_plan_callback(client, chat_id, data))
         task.add_done_callback(_log_task_exception)
+    elif data.startswith("proposal:"):
+        task = asyncio.create_task(handle_proposal_callback(client, chat_id, data))
+        task.add_done_callback(_log_task_exception)
 
 # ── Main loop ─────────────────────────────────────────────────────────────────
 

package/latticeai/runtime/chat_wiring.py

@@ -4,6 +4,10 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
+from latticeai.runtime.permission_mode_wiring import (
+    bind_dispatch_permission_mode,
+    resolve_active_permission_mode,
+)
 from latticeai.services.router_context import InteractionRouterContext, ToolRouterContext
 
 
@@ -19,6 +23,9 @@ def build_chat_agent_runtime_from_context(
     hooks: Any,
     brain_memory: Any,
 ) -> Any:
+    # Ensure dispatch + agent share the same autonomy dial before the runtime
+    # is constructed (process-wide service; data_dir refined later at router mount).
+    bind_dispatch_permission_mode()
     return build_agent_runtime(
         model_router=model_router,
         execute_tool=execute_tool,
@@ -28,6 +35,7 @@ def build_chat_agent_runtime_from_context(
         audit=audit,
         hooks=hooks,
         brain_memory=brain_memory,
+        permission_mode=resolve_active_permission_mode,
     )
 
 

package/latticeai/runtime/context_runtime.py

@@ -13,6 +13,7 @@ def build_context_runtime(
     gardener: Any,
     require_auth: bool,
     allowed_scopes_for_user: Callable[[Any], Any],
+    artifact_ledger: Any = None,
 ) -> Dict[str, Any]:
     """Construct search, brain memory, and context assembly services."""
 
@@ -41,15 +42,25 @@ def build_context_runtime(
                 allowed = allowed_scopes_for_user(user_email)
         return gardener.get_relevant_context(q, allowed_workspaces=allowed, **kw)
 
+    # Re-search loop (v9.9.6): files this conversation just produced are a
+    # deterministic context section, so "그 파일에 다크모드 넣어줘" works before
+    # asynchronous indexing catches up. Optional — absent ledger, absent section.
+    if artifact_ledger is None:
+        from latticeai.core.artifact_ledger import ArtifactLedger
+
+        artifact_ledger = ArtifactLedger()
+
     context_assembler = ContextAssembler(
         memory_recall=memory_service.recall,
         hybrid_search=scoped_hybrid_search,
         notes_context=scoped_notes_context,
+        recent_artifacts=artifact_ledger.recent,
     )
 
     return {
         "SEARCH_SERVICE": search_service,
         "BRAIN_MEMORY": brain_memory,
         "CONTEXT_ASSEMBLER": context_assembler,
+        "ARTIFACT_LEDGER": artifact_ledger,
         "_scoped_hybrid_search": scoped_hybrid_search,
     }

package/latticeai/runtime/permission_mode_wiring.py

@@ -0,0 +1,116 @@
+"""Wire PermissionMode into the running app without a large app_factory rewrite.
+
+Creates one process-wide :class:`PermissionModeService`, points
+``ToolDispatchService.permission_mode`` at it, and registers the HTTP dial.
+Called from ``register_review_and_brain_tail_routers`` (which already has
+``data_dir``, ``require_user``, ``append_audit_event``) and from
+``build_chat_agent_runtime_from_context`` so the agent loop sees the same dial.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from latticeai.core.permission_mode import DEFAULT_MODE, normalize_mode
+from latticeai.services.permission_mode_service import PermissionModeService
+
+_LOCK = threading.Lock()
+_SHARED: Optional[PermissionModeService] = None
+
+
+def _default_data_dir() -> Path:
+    raw = os.environ.get("LATTICEAI_DATA_DIR", "").strip()
+    if raw:
+        return Path(raw)
+    return Path.home() / ".ltcai"
+
+
+def _env_default_mode() -> Any:
+    return normalize_mode(os.environ.get("LATTICEAI_PERMISSION_MODE", DEFAULT_MODE.value))
+
+
+def get_permission_mode_service(
+    *,
+    data_dir: Optional[Path] = None,
+    audit: Optional[Callable[..., None]] = None,
+) -> PermissionModeService:
+    """Process-wide singleton.
+
+    An early lazy caller (a tool dispatch before routers are mounted) would
+    otherwise pin the service to the fallback ``data_dir`` with no audit sink.
+    Explicit arguments therefore *rebind* an already-created service instead of
+    being silently dropped, so the app's real data dir and audit log always win.
+    """
+    global _SHARED
+    with _LOCK:
+        if _SHARED is None:
+            _SHARED = PermissionModeService(
+                data_dir=Path(data_dir) if data_dir is not None else _default_data_dir(),
+                default_mode=_env_default_mode(),
+                audit=audit,
+            )
+            return _SHARED
+        if data_dir is not None:
+            _SHARED.rebind_data_dir(Path(data_dir))
+        if audit is not None:
+            _SHARED.rebind_audit(audit)
+        return _SHARED
+
+
+def resolve_active_permission_mode(
+    *,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+) -> Any:
+    return get_permission_mode_service().resolve(
+        user_email=user_email, workspace_id=workspace_id,
+    )
+
+
+def bind_dispatch_permission_mode(dispatch_service: Any = None) -> None:
+    """Point tool dispatch at the shared mode resolver.
+
+    The bound callable accepts scope kwargs so per-user and per-workspace
+    overrides actually reach ``enforce_policy`` — an unscoped resolver would
+    always return the process-wide default and make the dial a no-op.
+    """
+    from latticeai.services.tool_dispatch import DEFAULT_TOOL_DISPATCH_SERVICE
+
+    service = dispatch_service or DEFAULT_TOOL_DISPATCH_SERVICE
+    service.permission_mode = resolve_active_permission_mode
+
+
+def register_permission_mode_router(
+    app: Any,
+    *,
+    require_user: Callable[..., str],
+    data_dir: Optional[Path] = None,
+    append_audit_event: Optional[Callable[..., None]] = None,
+) -> Any:
+    """Install GET/POST /api/permission-mode on ``app``. Idempotent by route path."""
+    from latticeai.api.permission_mode import create_permission_mode_router
+
+    svc = get_permission_mode_service(data_dir=data_dir, audit=append_audit_event)
+    bind_dispatch_permission_mode()
+    # Skip if already mounted (re-entrant factory / tests).
+    existing = {
+        getattr(route, "path", None)
+        for route in getattr(app, "routes", ())
+    }
+    if "/api/permission-mode" in existing:
+        return svc
+    app.include_router(
+        create_permission_mode_router(service=svc, require_user=require_user)
+    )
+    return svc
+
+
+__all__ = [
+    "get_permission_mode_service",
+    "resolve_active_permission_mode",
+    "bind_dispatch_permission_mode",
+    "register_permission_mode_router",
+]

package/latticeai/runtime/router_registration.py

@@ -653,4 +653,13 @@ def register_review_and_brain_tail_routers(
             workspace_service=workspace_service,
         ),
     )
+    # Permission mode dial (v9.9.8): mount last so data_dir + audit are known.
+    from latticeai.runtime.permission_mode_wiring import register_permission_mode_router
+
+    register_permission_mode_router(
+        app,
+        require_user=require_user,
+        data_dir=data_dir,
+        append_audit_event=append_audit_event,
+    )
     return brain_network

package/latticeai/services/app_context.py

@@ -33,6 +33,9 @@ class AppContext:
     local_kg_watcher: Any = None
     chat_service: Any = None
     context_assembler: Any = None
+    # Re-search loop (v9.9.6): conversation-scoped ledger of just-written
+    # artifacts, so a follow-up turn sees them before indexing catches up.
+    artifact_ledger: Any = None
     brain_memory: Any = None
     # Unified ingestion gateway (lattice_brain.ingestion.IngestionPipeline);
     # None when the knowledge graph is disabled.

package/latticeai/services/architecture_readiness.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
 
-ARCHITECTURE_VERSION_TARGET = "9.9.5"
+ARCHITECTURE_VERSION_TARGET = "10.0.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/brain_intelligence.py

@@ -391,6 +391,111 @@ class BrainIntelligenceService:
             "generated_at": _now(),
         }
 
+    def garden_overview(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None,
+        limit: int = 8,
+    ) -> Dict[str, Any]:
+        """The knowledge garden in four beds (v9.9.7).
+
+        Living Brain answers "how healthy is my knowledge?" in aggregate.
+        A gardener asks four concrete questions instead, and this answers all
+        four from one workspace-scoped graph sample plus the memory tier:
+
+        * **recent** — what came in lately (the garden's new growth);
+        * **contradictions** — what disagrees with itself (needs weeding);
+        * **stale** — what has not been touched in a long time;
+        * **frequent** — what the rest of the graph leans on most (by degree).
+
+        Read-only and honest: when the graph is unavailable every bed is empty
+        and ``available`` is false — the view never invents plants.
+        """
+        # Explicit 0 clamps to 1 — `limit or 8` would silently re-expand it.
+        try:
+            limit = max(1, min(int(limit), 50))
+        except (TypeError, ValueError):
+            limit = 8
+        sample = self._graph_sample(workspace_id=workspace_id)
+        nodes, edges = sample["nodes"], sample["edges"]
+        now = datetime.now(timezone.utc)
+        recent_cutoff = now - timedelta(days=_RECENT_DAYS)
+        stale_cutoff = now - timedelta(days=_STALE_DAYS)
+
+        def _slim(node: Dict[str, Any], **extra: Any) -> Dict[str, Any]:
+            return {
+                "id": node.get("id"),
+                "type": node.get("type"),
+                "title": str(node.get("title") or "")[:120],
+                "updated_at": node.get("updated_at"),
+                **extra,
+            }
+
+        recent: List[Dict[str, Any]] = []
+        stale: List[Dict[str, Any]] = []
+        for node in nodes:
+            # Chunks are retrieval plumbing, not knowledge a gardener tends.
+            if str(node.get("type") or "") == "Chunk":
+                continue
+            ts = _parse_ts(node.get("updated_at"))
+            if ts is None:
+                continue
+            if ts >= recent_cutoff:
+                recent.append(node)
+            elif ts < stale_cutoff:
+                stale.append(node)
+        recent.sort(key=lambda n: str(n.get("updated_at") or ""), reverse=True)
+        stale.sort(key=lambda n: str(n.get("updated_at") or ""))
+
+        # "Frequent" is degree, not a guess: how many relations actually point
+        # at a node. Chunks are retrieval plumbing, never garden plants.
+        degree: Dict[str, int] = {}
+        for edge in edges:
+            for key in ("source", "target"):
+                node_id = str(edge.get(key) or "")
+                if node_id:
+                    degree[node_id] = degree.get(node_id, 0) + 1
+        by_id = {str(node.get("id")): node for node in nodes}
+        frequent = [
+            _slim(by_id[node_id], degree=count)
+            for node_id, count in sorted(degree.items(), key=lambda kv: kv[1], reverse=True)
+            if node_id in by_id and str(by_id[node_id].get("type") or "") != "Chunk"
+        ][:limit]
+
+        contradiction_items: List[Dict[str, Any]] = []
+        contradiction_count = 0
+        try:
+            found = self.contradictions(user_email=user_email, workspace_id=workspace_id)
+            items = found.get("items") if isinstance(found, dict) else None
+            if isinstance(items, list):
+                contradiction_count = len(items)
+                contradiction_items = items[:limit]
+        except Exception:  # noqa: BLE001 — one empty bed, never a broken view
+            LOGGER.exception("garden overview contradictions failed")
+
+        return {
+            "available": sample["available"],
+            "window_days": _RECENT_DAYS,
+            "stale_threshold_days": _STALE_DAYS,
+            "beds": {
+                "recent": {
+                    "count": len(recent),
+                    "items": [_slim(node) for node in recent[:limit]],
+                },
+                "contradictions": {
+                    "count": contradiction_count,
+                    "items": contradiction_items,
+                },
+                "stale": {
+                    "count": len(stale),
+                    "items": [_slim(node) for node in stale[:limit]],
+                },
+                "frequent": {
+                    "count": len(frequent),
+                    "items": frequent,
+                },
+            },
+            "generated_at": _now(),
+        }
+
     # ── graph-layer proactive quality (v9.6.x) ───────────────────────────
 
     def graph_duplicates(