npm - ltcai - Versions diffs - 9.9.3 → 9.9.5 - Mend

ltcai 9.9.3 → 9.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (89) hide show

package/README.md +39 -38
package/docs/CHANGELOG.md +100 -0
package/docs/COMMUNITY_AND_PLUGINS.md +1 -1
package/docs/DEVELOPMENT.md +1 -1
package/docs/ONBOARDING.md +1 -1
package/docs/OPERATIONS.md +1 -1
package/docs/SURFACE_PARITY.md +53 -0
package/docs/TRUST_MODEL.md +1 -1
package/docs/WHY_LATTICE.md +1 -1
package/docs/kg-schema.md +1 -1
package/lattice_brain/__init__.py +1 -1
package/lattice_brain/graph/_kg_common.py +335 -0
package/lattice_brain/graph/discovery_index.py +8 -1
package/lattice_brain/graph/ingest.py +43 -9
package/lattice_brain/graph/projection.py +221 -37
package/lattice_brain/graph/rerank.py +160 -0
package/lattice_brain/graph/retrieval.py +90 -455
package/lattice_brain/graph/retrieval_policy.py +174 -0
package/lattice_brain/graph/retrieval_reads.py +459 -0
package/lattice_brain/graph/retrieval_vector.py +122 -2
package/lattice_brain/graph/store.py +2 -0
package/lattice_brain/portability.py +41 -12
package/lattice_brain/quality.py +26 -6
package/lattice_brain/runtime/multi_agent.py +1 -1
package/latticeai/__init__.py +1 -1
package/latticeai/api/chat.py +6 -0
package/latticeai/api/chat_agent_http.py +262 -52
package/latticeai/api/chat_contracts.py +1 -1
package/latticeai/api/chat_intents.py +37 -18
package/latticeai/api/chat_stream.py +76 -2
package/latticeai/api/knowledge_graph.py +35 -1
package/latticeai/core/agent.py +420 -27
package/latticeai/core/enterprise.py +5 -0
package/latticeai/core/file_generation.py +130 -5
package/latticeai/core/legacy_compatibility.py +1 -1
package/latticeai/core/marketplace.py +1 -1
package/latticeai/core/run_store.py +245 -0
package/latticeai/core/workspace_os.py +1 -1
package/latticeai/integrations/telegram_bot.py +82 -23
package/latticeai/models/router.py +25 -12
package/latticeai/services/architecture_readiness.py +1 -1
package/latticeai/services/command_center.py +90 -1
package/latticeai/services/folder_watch.py +5 -0
package/latticeai/services/funnel_metrics.py +9 -1
package/latticeai/services/product_readiness.py +1 -1
package/latticeai/services/search_service.py +43 -13
package/latticeai/services/tool_dispatch.py +56 -0
package/package.json +2 -1
package/scripts/bench_agent_smoke.py +410 -0
package/scripts/check_current_release_docs.mjs +1 -1
package/scripts/funnel_soft_gate.py +192 -0
package/scripts/run_sidecar_e2e.mjs +159 -0
package/src-tauri/Cargo.lock +1 -1
package/src-tauri/Cargo.toml +1 -1
package/src-tauri/tauri.conf.json +1 -1
package/static/app/asset-manifest.json +29 -28
package/static/app/assets/Act-DmxfbqBp.js +1 -0
package/static/app/assets/{Brain-DEY9jLVt.js → Brain-DK_zKCda.js} +2 -2
package/static/app/assets/BrainHome-CCE_0hni.js +2 -0
package/static/app/assets/BrainSignals-r_J68_zh.js +1 -0
package/static/app/assets/{Capture-CVZ09QXi.js → Capture-CvxwzpJZ.js} +1 -1
package/static/app/assets/{CommandPalette-DepwOQFv.js → CommandPalette-CVLiFIQC.js} +1 -1
package/static/app/assets/{Library-Bp0n-HlW.js → Library-4As9VUvy.js} +1 -1
package/static/app/assets/{LivingBrain-DxP4efJF.js → LivingBrain-BVWk58MW.js} +1 -1
package/static/app/assets/{ProductFlow-DRbm7NEq.js → ProductFlow-B-Tz0Um4.js} +1 -1
package/static/app/assets/{ReviewCard-C4HAO7A3.js → ReviewCard-Va3fPQuj.js} +1 -1
package/static/app/assets/{System-ByQcmJW-.js → System-DSR2zKWd.js} +1 -1
package/static/app/assets/{bot-BNDyZLR7.js → bot-VmP0kkeA.js} +1 -1
package/static/app/assets/circle-pause-T9POo4qy.js +1 -0
package/static/app/assets/{circle-play-BkhdcHgd.js → circle-play-Bz5iTD0p.js} +1 -1
package/static/app/assets/{cpu-C6jjYm6i.js → cpu-CJhjRtNq.js} +1 -1
package/static/app/assets/{folder-open-DjGIvDBQ.js → folder-open-B2K_22VI.js} +1 -1
package/static/app/assets/{hard-drive-BlSbwSaT.js → hard-drive-CjJtYqHf.js} +1 -1
package/static/app/assets/{index-Bge3DXW7.css → index-7FAfYm4v.css} +1 -1
package/static/app/assets/{index-CHu7cgj3.js → index-CEu0Wqjl.js} +3 -3
package/static/app/assets/{input-DVDI0YR3.js → input-CSi6OBJ9.js} +1 -1
package/static/app/assets/{navigation-BddhEWA0.js → navigation-BPQqEQwr.js} +1 -1
package/static/app/assets/{network-pYQt5oBu.js → network-Ck1nqc-v.js} +1 -1
package/static/app/assets/{primitives-D7gCdEvS.js → primitives-B2f9N7Dh.js} +1 -1
package/static/app/assets/{shield-alert-K9RKGQeg.js → shield-alert-yA_Y8lOB.js} +1 -1
package/static/app/assets/{textarea-sqQmoBKL.js → textarea-C4wM0D-Z.js} +1 -1
package/static/app/assets/{useFocusTrap-7EV9dFP2.js → useFocusTrap-CsnIhsDJ.js} +1 -1
package/static/app/assets/utils-BqoznzGP.js +7 -0
package/static/app/index.html +4 -4
package/static/sw.js +1 -1
package/static/app/assets/Act-DmdruVKV.js +0 -1
package/static/app/assets/BrainHome-CeNaxjP1.js +0 -2
package/static/app/assets/BrainSignals-CStjIqYi.js +0 -1
package/static/app/assets/utils-uQYKXNeq.js +0 -7

package/latticeai/core/enterprise.py CHANGED Viewed

@@ -52,6 +52,11 @@ class EnterpriseCapability(str, Enum):
     DLP_POLICY = "dlp_policy"
     EDISCOVERY = "ediscovery"
     ADMIN_POLICY_PACKS = "admin_policy_packs"
+    # Human review-before-promote governance for knowledge-graph concept
+    # promotions (review 2026-07-25 Wave 4). Community users can opt in per
+    # deployment via LATTICEAI_GRAPH_PROMOTION_REVIEW; this capability is the
+    # seam for Enterprise policy packs that mandate reviewed promotions.
+    GRAPH_PROMOTION_REVIEW = "graph_promotion_review"
 @runtime_checkable

package/latticeai/core/file_generation.py CHANGED Viewed

@@ -358,6 +358,23 @@ _BUNDLE_HTML_RULE = (
     "blocks, no inline behavior scripts."
 )
+# Vite/React bundles need a module entry point, not classic script tags.
+_BUNDLE_HTML_MODULE_RULE = (
+    "Produce ONE complete HTML5 document: <!DOCTYPE html>, <html>, <head> with "
+    "<meta charset=\"utf-8\"> and a <title>, and a closed </html> tag. "
+    "This page is the Vite entry of a React project: the <body> must contain "
+    "<div id=\"root\"></div> and load the app with "
+    "<script type=\"module\" src=\"/src/main.jsx\"></script> just before "
+    "</body>. No inline <style> blocks, no other scripts, no external files."
+)
+def _bundle_html_rule(bundle_files: List[str]) -> str:
+    """Pick the HTML bundle rule that matches the bundle's technology."""
+    if any(str(path).lower().endswith((".jsx", ".tsx")) for path in bundle_files):
+        return _BUNDLE_HTML_MODULE_RULE
+    return _BUNDLE_HTML_RULE
 def build_file_generation_context(
     target_path: str,
@@ -381,7 +398,7 @@ def build_file_generation_context(
     ]
     type_rule = _TYPE_RULES.get(ext)
     if bundle_files and ext in (".html", ".htm"):
-        type_rule = _BUNDLE_HTML_RULE
+        type_rule = _bundle_html_rule(bundle_files)
     if type_rule:
         parts.append(f"- {type_rule}")
     if bundle_files:
@@ -608,16 +625,116 @@ _EXPLICIT_FILENAME_RE = re.compile(
     re.IGNORECASE,
 )
 _PROJECT_NAME_RE = re.compile(r"([A-Za-z][A-Za-z0-9_-]{1,30})\s*(?:앱|app\b)", re.IGNORECASE)
+# React/Vite intent: the react keyword is specific enough on its own.
+_REACT_HINT_RE = re.compile(r"(?<![a-z0-9])react(?![a-z0-9])|리액트")
+_VITE_HINT_RE = re.compile(r"(?<![a-z0-9])vite(?![a-z0-9])")
+# Python package intent: language + package word, both required.
+_PYTHON_HINT_RE = re.compile(r"(?<![a-z0-9])python(?![a-z0-9])|파이썬")
+_PACKAGE_HINT_RE = re.compile(r"패키지|(?<![a-z0-9])package(?![a-z0-9])")
+_PKG_NAME_RE = re.compile(
+    r"([A-Za-z][A-Za-z0-9_-]{1,30})\s*(?:패키지|package\b)", re.IGNORECASE
+)
+def _react_manifest(text: str) -> Dict[str, Any]:
+    """Vite + React starter manifest (review Wave 4: manifest 확장)."""
+    name_match = _PROJECT_NAME_RE.search(text)
+    name = f"{name_match.group(1).lower()}-app" if name_match else "react-app"
+    return {
+        "name": name,
+        "kind": "react",
+        "files": [
+            {
+                "path": "package.json",
+                "brief": (
+                    f'Vite React app manifest: strictly valid JSON with "name": "{name}", '
+                    '"private": true, "type": "module", "scripts" {"dev": "vite", '
+                    '"build": "vite build", "preview": "vite preview"}, "dependencies" '
+                    'with react and react-dom (^18), and "devDependencies" with vite '
+                    "and @vitejs/plugin-react."
+                ),
+            },
+            {
+                "path": "index.html",
+                "brief": (
+                    "The Vite entry HTML: <div id=\"root\"></div> in <body> and "
+                    "<script type=\"module\" src=\"/src/main.jsx\"></script> just "
+                    "before </body>. No inline styles or scripts."
+                ),
+            },
+            {
+                "path": "src/main.jsx",
+                "brief": (
+                    "React entry: createRoot from react-dom/client rendering <App /> "
+                    "into #root; imports ./App.jsx and ./App.css."
+                ),
+            },
+            {
+                "path": "src/App.jsx",
+                "brief": (
+                    "The main App component implementing the user's request as one "
+                    "self-contained React component (hooks allowed, no extra deps)."
+                ),
+            },
+            {
+                "path": "src/App.css",
+                "brief": "All visual styles for the App component.",
+            },
+        ],
+    }
+def _python_package_manifest(text: str) -> Dict[str, Any]:
+    """Multi-file Python package manifest (review Wave 4: manifest 확장)."""
+    name_match = _PKG_NAME_RE.search(text)
+    raw_name = name_match.group(1).lower() if name_match else "my_package"
+    module = re.sub(r"[^a-z0-9_]", "_", raw_name)
+    if not re.match(r"[a-z_]", module):
+        module = f"pkg_{module}"
+    return {
+        "name": module,
+        "kind": "python",
+        "files": [
+            {
+                "path": f"{module}/__init__.py",
+                "brief": (
+                    f"Package init for {module}: import and re-export the public "
+                    "API from .core with an explicit __all__."
+                ),
+            },
+            {
+                "path": f"{module}/core.py",
+                "brief": (
+                    "Implement the user's request as clean, documented functions/"
+                    "classes with type hints. Standard library only."
+                ),
+            },
+            {
+                "path": f"{module}/cli.py",
+                "brief": (
+                    "argparse CLI wrapping the core API: a main() function and an "
+                    'if __name__ == "__main__": main() guard.'
+                ),
+            },
+            {
+                "path": "README.md",
+                "brief": (
+                    f"Usage documentation for the {module} package: install, import "
+                    "example, and CLI example."
+                ),
+            },
+        ],
+    }
 def infer_project_manifest(message: str) -> Optional[Dict[str, Any]]:
-    """Infer a multi-file web-project manifest from a creation request.
+    """Infer a multi-file project manifest from a creation request.
     "todo 앱 html+css+js로 만들어줘" should yield real linked files, not one
     inlined page. Deliberately narrow and deterministic (weak local models
-    never see this decision): requires a creation verb, an HTML-page intent,
-    at least one *additional* named technology (css/js), and no explicit
-    filename. Single-type requests return ``None`` so the existing
+    never see this decision): requires a creation verb, a recognized project
+    intent (web page + css/js, React/Vite app, or Python package), and no
+    explicit filename. Single-type requests return ``None`` so the existing
     single-file flow is completely unchanged.
     """
     text = (message or "").strip()
@@ -626,6 +743,14 @@ def infer_project_manifest(message: str) -> Optional[Dict[str, Any]]:
     if _EXPLICIT_FILENAME_RE.search(text):
         return None
     lower = text.lower()
+    # Most-specific first: React (its own structure), then Python package,
+    # then the classic html+css/js web bundle.
+    if _REACT_HINT_RE.search(lower) or _VITE_HINT_RE.search(lower):
+        return _react_manifest(text)
+    if _PYTHON_HINT_RE.search(lower) and _PACKAGE_HINT_RE.search(lower):
+        return _python_package_manifest(text)
     wants_html = bool(_HTML_HINT_RE.search(lower))
     wants_css = bool(_CSS_HINT_RE.search(lower))
     wants_js = bool(_JS_HINT_RE.search(lower))

package/latticeai/core/legacy_compatibility.py CHANGED Viewed

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any, Dict, List
-LEGACY_COMPATIBILITY_VERSION = "9.9.3"
+LEGACY_COMPATIBILITY_VERSION = "9.9.5"
 @dataclass(frozen=True)

package/latticeai/core/marketplace.py CHANGED Viewed

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
-MARKETPLACE_VERSION = "9.9.3"
+MARKETPLACE_VERSION = "9.9.5"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent", "ingestion_bridge")

package/latticeai/core/run_store.py ADDED Viewed

@@ -0,0 +1,245 @@
+"""Durable persistence for paused agent runs (review 2026-07-25 Wave 0.1).
+The ``awaiting_approval`` loop parked runs in an in-process dict, so a server
+restart between pause and resume turned every outstanding approval into a 404
+("승인하려다 사라짐"). This store writes each paused run to one JSON file under
+the data dir, so a valid, unexpired token can resume its run across restarts
+and across worker processes.
+Design constraints (deliberate, matching :mod:`latticeai.services.funnel_metrics`):
+* **One JSON file per run**, atomic replace on write — no new dependencies.
+* **Fail-open on save, fail-closed on resume.** A persistence error never
+  breaks the pause response (the in-memory path still works); a load error on
+  resume is treated as "run not found".
+* **Tokens are never stored in plaintext.** Only the SHA-256 hex digest is
+  persisted; resume hashes the presented token and compares digests.
+* **Wall-clock expiry.** The in-memory dict keeps its monotonic deadline, but
+  monotonic time does not survive a restart — the durable record carries an
+  absolute UTC epoch and files past it are swept, never resumed.
+"""
+from __future__ import annotations
+import hashlib
+import json
+import logging
+import os
+import re
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from latticeai.core.agent import AgentRunContext, AgentState
+from latticeai.core.agent_trace import LoopTrace
+LOGGER = logging.getLogger(__name__)
+# run_id comes from ``secrets.token_urlsafe`` — validate before any path use
+# so a crafted id can never traverse out of the store directory.
+_RUN_ID_RE = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
+def hash_approval_token(token: str) -> str:
+    """Stable digest used both at save and at resume comparison time."""
+    return hashlib.sha256(str(token or "").encode("utf-8")).hexdigest()
+def serialize_run_context(ctx: AgentRunContext) -> Dict[str, Any]:
+    """Reduce an :class:`AgentRunContext` to plain JSON-safe data."""
+    return {
+        "state": ctx.state.value,
+        "plan": ctx.plan,
+        "transcript": ctx.transcript,
+        "retry_count": ctx.retry_count,
+        "state_history": ctx.state_history,
+        "corrections": ctx.corrections,
+        "final_message": ctx.final_message,
+        "rollback_log": ctx.rollback_log,
+        "executing_model": ctx.executing_model,
+        "reviewing_model": ctx.reviewing_model,
+        "approved_by_human": ctx.approved_by_human,
+        "trace": {"events": ctx.trace.events, "truncated": ctx.trace.truncated},
+    }
+def restore_run_context(payload: Dict[str, Any]) -> AgentRunContext:
+    """Rebuild an :class:`AgentRunContext` from :func:`serialize_run_context`."""
+    ctx = AgentRunContext()
+    try:
+        ctx.state = AgentState(str(payload.get("state") or AgentState.WAITING_APPROVAL.value))
+    except ValueError:
+        ctx.state = AgentState.WAITING_APPROVAL
+    ctx.plan = dict(payload.get("plan") or {})
+    ctx.transcript = list(payload.get("transcript") or [])
+    ctx.retry_count = int(payload.get("retry_count") or 0)
+    ctx.state_history = list(payload.get("state_history") or [])
+    ctx.corrections = list(payload.get("corrections") or [])
+    ctx.final_message = str(payload.get("final_message") or "")
+    ctx.rollback_log = list(payload.get("rollback_log") or [])
+    ctx.executing_model = payload.get("executing_model")
+    ctx.reviewing_model = payload.get("reviewing_model")
+    ctx.approved_by_human = bool(payload.get("approved_by_human"))
+    trace_payload = payload.get("trace") or {}
+    trace = LoopTrace()
+    trace.events = list(trace_payload.get("events") or [])
+    trace.truncated = int(trace_payload.get("truncated") or 0)
+    ctx.trace = trace
+    return ctx
+class AgentRunStore:
+    """One-JSON-file-per-run persistence for paused approval runs."""
+    def __init__(self, root: Path) -> None:
+        self._root = Path(root)
+    def _path_for(self, run_id: str) -> Optional[Path]:
+        if not _RUN_ID_RE.fullmatch(str(run_id or "")):
+            return None
+        return self._root / f"{run_id}.json"
+    # ── writes ───────────────────────────────────────────────────────────
+    def save(
+        self,
+        run_id: str,
+        *,
+        ctx: AgentRunContext,
+        req_payload: Dict[str, Any],
+        language_hint: str,
+        user: str,
+        token: str,
+        expires_epoch: float,
+        expires_at: str,
+        legacy_context: bool = False,
+    ) -> bool:
+        """Persist a paused run. Best-effort: returns False on any failure."""
+        path = self._path_for(run_id)
+        if path is None:
+            return False
+        record = {
+            "version": 1,
+            "run_id": run_id,
+            "user": user,
+            "language_hint": language_hint,
+            "token_hash": hash_approval_token(token),
+            "expires_epoch": float(expires_epoch),
+            "expires_at": expires_at,
+            "legacy_context": bool(legacy_context),
+            "req": req_payload,
+            "ctx": serialize_run_context(ctx),
+        }
+        try:
+            self._root.mkdir(parents=True, exist_ok=True)
+            fd, tmp_name = tempfile.mkstemp(prefix=path.name, dir=str(self._root))
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                    json.dump(record, handle, ensure_ascii=False)
+                os.replace(tmp_name, path)
+            finally:
+                if os.path.exists(tmp_name):
+                    try:
+                        os.unlink(tmp_name)
+                    except OSError:
+                        pass
+            return True
+        except Exception as exc:  # noqa: BLE001 — pause must still answer without disk
+            LOGGER.warning("agent run store save failed for %s: %s", run_id, exc)
+            return False
+    def delete(self, run_id: str) -> None:
+        path = self._path_for(run_id)
+        if path is None:
+            return
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as exc:
+            LOGGER.warning("agent run store delete failed for %s: %s", run_id, exc)
+    # ── reads ────────────────────────────────────────────────────────────
+    def load(self, run_id: str) -> Optional[Dict[str, Any]]:
+        """Raw persisted record, or None when missing/corrupt/invalid id."""
+        path = self._path_for(run_id)
+        if path is None:
+            return None
+        try:
+            record = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except Exception as exc:  # noqa: BLE001 — corrupt record == not found
+            LOGGER.warning("agent run store load failed for %s: %s", run_id, exc)
+            return None
+        if not isinstance(record, dict) or record.get("run_id") != run_id:
+            return None
+        return record
+    def pending_summaries(self, user: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Unexpired pending runs (optionally per user) for surfacing in UI."""
+        summaries: List[Dict[str, Any]] = []
+        now = time.time()
+        try:
+            paths = sorted(self._root.glob("*.json"))
+        except OSError:
+            return summaries
+        for path in paths:
+            try:
+                record = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:  # noqa: BLE001
+                continue
+            if not isinstance(record, dict):
+                continue
+            if float(record.get("expires_epoch") or 0) <= now:
+                continue
+            if user is not None and record.get("user") != user:
+                continue
+            plan = (record.get("ctx") or {}).get("plan") or {}
+            summaries.append({
+                "run_id": record.get("run_id"),
+                "user": record.get("user"),
+                "goal": str(plan.get("goal") or "")[:200],
+                "expires_at": record.get("expires_at"),
+            })
+        return summaries
+    def sweep_expired(
+        self,
+        now_epoch: Optional[float] = None,
+        *,
+        retention_seconds: float = 86400.0,
+    ) -> int:
+        """Remove long-expired run files; returns how many were removed.
+        Recently expired records are *kept* for ``retention_seconds`` so that
+        a resume attempt after expiry can still answer 410 with a one-click
+        replan hint (the original request message) instead of a bare 404.
+        """
+        removed = 0
+        now = time.time() if now_epoch is None else float(now_epoch)
+        try:
+            paths = list(self._root.glob("*.json"))
+        except OSError:
+            return removed
+        for path in paths:
+            try:
+                record = json.loads(path.read_text(encoding="utf-8"))
+                expires = float(record.get("expires_epoch") or 0)
+            except Exception:  # noqa: BLE001 — unreadable == expired garbage
+                expires = -float(retention_seconds)
+            if expires + float(retention_seconds) <= now:
+                try:
+                    path.unlink(missing_ok=True)
+                    removed += 1
+                except OSError:
+                    pass
+        return removed
+__all__ = [
+    "AgentRunStore",
+    "hash_approval_token",
+    "restore_run_context",
+    "serialize_run_context",
+]

package/latticeai/core/workspace_os.py CHANGED Viewed

@@ -49,7 +49,7 @@ __all__ = [
     "remove_skill_directory",
 ]
-WORKSPACE_OS_VERSION = "9.9.3"
+WORKSPACE_OS_VERSION = "9.9.5"
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/integrations/telegram_bot.py CHANGED Viewed

@@ -40,7 +40,8 @@ UPLOAD_DOC_URL  = f"{BASE_URL}/upload/document"
 AGENT_RESUME_URL      = f"{BASE_URL}/agent/resume"
 AGENT_WORKSPACE       = Path(env_value("LATTICEAI_AGENT_ROOT", "agent_workspace")).resolve()
-# Pending plan approvals: context_id → (chat_id, executing_model, reviewing_model)
+# Pending plan approvals keyed by run_id (or legacy context_id).
+# Values: chat_id, models, and the resume credentials (token and/or legacy).
 _bot_pending_plans: dict[str, dict] = {}
 MAX_TELEGRAM_FILE_BYTES = 45 * 1024 * 1024
 INVITE_CODE           = env_value("LATTICEAI_INVITE_CODE")
@@ -711,35 +712,65 @@ async def send_generated_files(client, chat_id, generated_files):
 # ── Plan approval (Human-in-the-loop) ────────────────────────────────────────
+def _approval_pause_id(data: dict) -> str:
+    """Stable key for a paused plan: run_id preferred, legacy context_id fallback."""
+    return str(data.get("run_id") or data.get("context_id") or "")
+def _is_approval_pause(data: dict) -> bool:
+    status = str(data.get("status") or "")
+    return status in {"waiting_approval", "awaiting_approval"}
 async def send_plan_for_approval(client, chat_id, data: dict) -> None:
-    """Show the agent plan to the user and present Done/Cancel buttons."""
-    context_id = data.get("context_id", "")
-    plan = data.get("plan", {})
-    goal = plan.get("goal", "")
-    steps = plan.get("steps", [])
+    """Show the agent plan to the user and present Done/Cancel buttons.
+    Handles both the modern ``awaiting_approval`` (run_id + token) and the
+    legacy ``waiting_approval`` / ``context_id`` wire contracts (v9.9.5
+    SURFACE_PARITY — Telegram approval flow).
+    """
+    pause_id = _approval_pause_id(data)
+    if not pause_id:
+        await send_message(client, chat_id, "❌ 승인할 계획을 식별할 수 없습니다.")
+        return
+    plan = data.get("plan", {}) or {}
+    goal = plan.get("goal") or (data.get("approval") or {}).get("plan_summary") or ""
+    steps = plan.get("steps", []) or data.get("non_auto_steps") or []
     p_model = data.get("planning_model", "current")
     e_model = data.get("executing_model", "current")
     r_model = data.get("reviewing_model", "current")
+    approval = data.get("approval") or {}
+    expires_at = approval.get("expires_at")
     lines = ["📋 *플래닝 완료* — 실행 전 확인해주세요\n"]
     if goal:
         lines.append(f"*목표:* {goal}\n")
     for i, step in enumerate(steps, 1):
-        desc = step.get("description") or step.get("action") or str(step)
+        if isinstance(step, dict):
+            desc = step.get("description") or step.get("action") or str(step)
+        else:
+            desc = str(step)
         lines.append(f"{i}. {desc}")
     lines.append(f"\n🧠 플래닝: `{p_model}`")
     lines.append(f"⚙️ 실행: `{e_model}`")
     lines.append(f"🔍 검토: `{r_model}`")
+    if expires_at:
+        lines.append(f"⏳ 승인 만료: `{expires_at}`")
-    _bot_pending_plans[context_id] = {
+    _bot_pending_plans[pause_id] = {
         "chat_id": chat_id,
+        "run_id": data.get("run_id") or pause_id,
+        "context_id": data.get("context_id"),
+        "approval_token": approval.get("token"),
+        "legacy": data.get("status") == "waiting_approval" or bool(data.get("context_id")),
         "executing_model": data.get("executing_model"),
         "reviewing_model": data.get("reviewing_model"),
     }
+    # callback_data max 64 bytes — pause ids are token_urlsafe(16) (~22 chars).
     keyboard = {"inline_keyboard": [[
-        {"text": "✅ Done — 실행 시작", "callback_data": f"plan:approve:{context_id}"},
-        {"text": "❌ 취소", "callback_data": f"plan:cancel:{context_id}"},
+        {"text": "✅ Done — 실행 시작", "callback_data": f"plan:approve:{pause_id}"},
+        {"text": "❌ 취소", "callback_data": f"plan:cancel:{pause_id}"},
     ]]}
     await send_message(client, chat_id, "\n".join(lines), reply_markup=keyboard)
@@ -749,8 +780,8 @@ async def handle_plan_callback(client, chat_id, data: str) -> None:
     parts = data.split(":", 2)
     if len(parts) != 3:
         return
-    _, action, context_id = parts
-    pending = _bot_pending_plans.get(context_id)
+    _, action, pause_id = parts
+    pending = _bot_pending_plans.get(pause_id)
     # A callback is bound to the chat that received the plan. Even two allowed
     # chats cannot approve or cancel each other's plan by replaying callback
@@ -758,9 +789,19 @@ async def handle_plan_callback(client, chat_id, data: str) -> None:
     if pending and int(pending.get("chat_id")) != int(chat_id):
         await send_message(client, chat_id, "❌ 다른 채팅의 작업은 처리할 수 없습니다.")
         return
-    pending = _bot_pending_plans.pop(context_id, None)
+    pending = _bot_pending_plans.pop(pause_id, None)
-    if action == "cancel" or not pending:
+    if action == "cancel":
+        if pending:
+            try:
+                resume_body = _resume_payload(pending, approved=False)
+                async with _server_client() as sc:
+                    await sc.post(AGENT_RESUME_URL, json=resume_body, timeout=30.0)
+            except Exception as exc:  # noqa: BLE001 — cancel is best-effort
+                logger.warning("telegram cancel resume failed: %s", safe_log_text(exc))
+        await send_message(client, chat_id, "❌ 작업이 취소되었습니다.")
+        return
+    if not pending:
         await send_message(client, chat_id, "❌ 작업이 취소되었습니다.")
         return
@@ -769,12 +810,11 @@ async def handle_plan_callback(client, chat_id, data: str) -> None:
     try:
         async with _server_client() as sc:
-            res = await sc.post(AGENT_RESUME_URL, json={
-                "context_id": context_id,
-                "approved": True,
-                "executing_model": pending.get("executing_model"),
-                "reviewing_model": pending.get("reviewing_model"),
-            }, timeout=300.0)
+            res = await sc.post(
+                AGENT_RESUME_URL,
+                json=_resume_payload(pending, approved=True),
+                timeout=300.0,
+            )
         data_r = res.json() if res.status_code == 200 else {}
         ans = data_r.get("response", f"❌ 서버 에러 ({res.status_code})")
         await send_message(client, chat_id, str(ans))
@@ -785,6 +825,25 @@ async def handle_plan_callback(client, chat_id, data: str) -> None:
         await send_message(client, chat_id, f"❌ 실행 중 오류: {e}")
+def _resume_payload(pending: dict, *, approved: bool) -> dict:
+    """Build /agent/resume body: token path preferred, else legacy context_id."""
+    body: dict = {
+        "approved": approved,
+        "executing_model": pending.get("executing_model"),
+        "reviewing_model": pending.get("reviewing_model"),
+    }
+    token = pending.get("approval_token")
+    run_id = pending.get("run_id")
+    # Unified durable store (9.9.5): token-gated resume works for both the
+    # modern awaiting_approval and the legacy human_in_loop pause.
+    if token and run_id:
+        body["run_id"] = run_id
+        body["approval_token"] = token
+        return body
+    body["context_id"] = pending.get("context_id") or run_id
+    return body
 # ── AI request task ───────────────────────────────────────────────────────────
 async def process_ai_request(client, chat_id, user_text, image_data=None):
@@ -794,8 +853,8 @@ async def process_ai_request(client, chat_id, user_text, image_data=None):
         data  = await ask_ai(client, user_text, image_data, agent_mode=not image_data)
         logger.info("ask_ai 완료: chat_id=%s result_keys=%s", chat_id, list(data.keys()) if isinstance(data, dict) else type(data))
-        # Human-in-the-loop: show plan and wait for approval
-        if isinstance(data, dict) and data.get("status") == "waiting_approval":
+        # Approval pause (legacy waiting_approval or modern awaiting_approval)
+        if isinstance(data, dict) and _is_approval_pause(data):
             await send_plan_for_approval(client, chat_id, data)
             return
@@ -887,7 +946,7 @@ async def handle_command(client, chat_id, command: str, args: str):
         await send_chat_action(client, chat_id, "typing")
         data = await ask_ai(client, task_text, agent_mode=True,
                             executing_model=exec_model, reviewing_model=reviewing_model)
-        if isinstance(data, dict) and data.get("status") == "waiting_approval":
+        if isinstance(data, dict) and _is_approval_pause(data):
             await send_plan_for_approval(client, chat_id, data)
         else:
             ans = data.get("response", str(data)) if isinstance(data, dict) else str(data)