ltcai 9.9.5 → 9.9.9

package/latticeai/core/permission_mode.py

@@ -0,0 +1,296 @@
+"""Permission modes for agent/tool autonomy (v9.9.8).
+
+Frontier agents expose a mode dial (Claude Code: default → acceptEdits →
+auto → bypassPermissions; Cursor: allowlist → auto-review → run everything;
+Codex: approval × sandbox). LatticeAI maps the same idea onto the existing
+ToolRegistry + Change Governor without throwing those gates away.
+
+Modes
+-----
+* ``strict``  — current fail-closed defaults (every non-auto tool needs
+  approval; mutations become review proposals).
+* ``trusted`` — workspace autonomy: knowledge reads, workspace writes
+  (additive + mutation), and computer *observation* auto-run. Exec,
+  destructive, host-control, and system-sandbox writes still gate.
+* ``bypass``  — YOLO within the agent workspace. Hard circuit breakers
+  still fire (blocked path prefixes, destructive root/home removals,
+  system-sandbox writes that escape the workspace).
+
+Circuit breakers are mode-invariant: a mode never overrides a hard deny.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, Mapping, Optional, Set
+
+
+class PermissionMode(str, Enum):
+    STRICT = "strict"
+    TRUSTED = "trusted"
+    BYPASS = "bypass"
+
+
+DEFAULT_MODE = PermissionMode.STRICT
+
+# Computer-use split: observation is low-friction in trusted; control stays gated.
+COMPUTER_OBSERVATION_TOOLS: Set[str] = frozenset({
+    "computer_screenshot",
+    "computer_status",
+    "computer_use_status",
+    "chrome_status",
+    "vision_analyze",
+})
+
+COMPUTER_CONTROL_TOOLS: Set[str] = frozenset({
+    "computer_click",
+    "computer_type",
+    "computer_key",
+    "computer_scroll",
+    "computer_drag",
+    "computer_move",
+    "computer_open_app",
+    "computer_open_url",
+})
+
+KNOWLEDGE_READ_TOOLS: Set[str] = frozenset({
+    "knowledge_search",
+    "knowledge_tree",
+    "obsidian_search",
+    "obsidian_tree",
+    "knowledge_graph_search",
+    "knowledge_graph_graph",
+    "knowledge_graph_context",
+})
+
+WORKSPACE_WRITE_TOOLS: Set[str] = frozenset({
+    "write_file",
+    "edit_file",
+    "create_docx",
+    "create_xlsx",
+    "create_pptx",
+    "create_pdf",
+    "create_web_project",
+    "knowledge_save",
+    "obsidian_save",
+    "knowledge_graph_ingest",
+    "todo_write",
+})
+
+# Always blocked regardless of mode (Claude-style circuit breakers).
+HARD_BLOCK_SANDBOXES: Set[str] = frozenset({"system"})
+
+
+def normalize_mode(value: Any) -> PermissionMode:
+    """Parse user/API/env input into a PermissionMode; unknown → strict."""
+    if isinstance(value, PermissionMode):
+        return value
+    text = str(value or "").strip().lower()
+    aliases = {
+        "strict": PermissionMode.STRICT,
+        "default": PermissionMode.STRICT,
+        "manual": PermissionMode.STRICT,
+        "trusted": PermissionMode.TRUSTED,
+        "acceptedits": PermissionMode.TRUSTED,
+        "accept_edits": PermissionMode.TRUSTED,
+        "workspace": PermissionMode.TRUSTED,
+        "bypass": PermissionMode.BYPASS,
+        "bypasspermissions": PermissionMode.BYPASS,
+        "bypass_permissions": PermissionMode.BYPASS,
+        "yolo": PermissionMode.BYPASS,
+        "dangerously-skip-permissions": PermissionMode.BYPASS,
+    }
+    return aliases.get(text, DEFAULT_MODE)
+
+
+def mode_catalog() -> list[Dict[str, Any]]:
+    """UI/API catalog for the mode selector."""
+    return [
+        {
+            "id": PermissionMode.STRICT.value,
+            "label": "Strict",
+            "label_ko": "엄격",
+            "summary": "Reads auto; writes and exec need approval or review proposals.",
+            "summary_ko": "읽기는 자동, 쓰기·실행은 승인 또는 변경 제안.",
+            "risk": "low",
+            "requires_ack": False,
+        },
+        {
+            "id": PermissionMode.TRUSTED.value,
+            "label": "Trusted",
+            "label_ko": "신뢰",
+            "summary": "Workspace writes and knowledge reads auto-run; exec/desktop control still gated.",
+            "summary_ko": "워크스페이스 쓰기·지식 읽기 자동. 실행·데스크톱 제어는 승인 필요.",
+            "risk": "medium",
+            "requires_ack": False,
+        },
+        {
+            "id": PermissionMode.BYPASS.value,
+            "label": "Bypass",
+            "label_ko": "바이패스",
+            "summary": "YOLO inside the agent workspace. Hard circuit breakers still apply.",
+            "summary_ko": "에이전트 워크스페이스 안에서 전부 자동. 하드 차단만 남음.",
+            "risk": "high",
+            "requires_ack": True,
+            "warning": (
+                "Bypass skips routine approval prompts. Destructive system paths, "
+                "root/home wipes, and blocked prefixes remain denied."
+            ),
+            "warning_ko": (
+                "바이패스는 일상 승인 프롬프트를 건너뜁니다. 시스템 경로 파괴, "
+                "루트/홈 삭제, 차단 접두사는 계속 거부됩니다."
+            ),
+        },
+    ]
+
+
+def is_circuit_breaker(
+    tool_name: str,
+    policy: Mapping[str, Any],
+    args: Optional[Mapping[str, Any]] = None,
+) -> Optional[str]:
+    """Return a reason string when the call must be denied in every mode."""
+    risk = str(policy.get("risk") or "")
+    destructive = bool(policy.get("destructive"))
+
+    if destructive or risk == "destructive":
+        return "destructive action is always blocked"
+
+    # NOTE: system-sandbox writes are *mode-sensitive*, not circuit breakers —
+    # ``effective_auto_approve`` keeps them gated under every mode and the
+    # blocked-path-prefix guard upstream denies escapes outright. Deciding them
+    # here would make ``bypass`` unable to drive desktop control at all.
+
+    path = str((args or {}).get("path") or (args or {}).get("filename") or "")
+    if path:
+        normalized = path.replace("\\", "/")
+        # Root / home mass-delete style paths — Claude circuit breaker analogue.
+        if normalized in {"/", "~", "/home", "/Users"} or normalized.rstrip("/") in {"/", "~"}:
+            return f"circuit breaker: refusing path {path!r}"
+
+    command = str((args or {}).get("command") or (args or {}).get("cmd") or "")
+    lowered = command.lower()
+    if any(token in lowered for token in ("rm -rf /", "rm -rf ~", "rm -rf /*", "rm -rf $home")):
+        return "circuit breaker: refusing destructive shell command"
+
+    return None
+
+
+def effective_auto_approve(
+    mode: PermissionMode | str,
+    tool_name: str,
+    policy: Mapping[str, Any],
+    *,
+    change_class: Optional[str] = None,
+    args: Optional[Mapping[str, Any]] = None,
+) -> bool:
+    """Whether this tool call may run without an extra human approval prompt.
+
+    Does **not** override circuit breakers — callers must check
+    :func:`is_circuit_breaker` first and deny when it returns a reason.
+    """
+    mode = normalize_mode(mode)
+    if policy.get("auto_approve"):
+        return True
+
+    risk = str(policy.get("risk") or "")
+    sandbox = str(policy.get("sandbox") or "workspace")
+
+    if mode == PermissionMode.STRICT:
+        return False
+
+    if mode == PermissionMode.TRUSTED:
+        if tool_name in KNOWLEDGE_READ_TOOLS:
+            return True
+        if tool_name in COMPUTER_OBSERVATION_TOOLS:
+            return True
+        if tool_name in WORKSPACE_WRITE_TOOLS and sandbox == "workspace":
+            # Additive and mutation both auto under trusted; destructive still
+            # blocked by circuit breaker / risk check above.
+            if risk in {"write", "write_scoped", "read"} or change_class in {
+                "additive", "mutation", "read", None,
+            }:
+                if risk != "destructive" and not policy.get("destructive"):
+                    return True
+        # Explicit reads that were gated only for consent (local_list etc.) stay gated.
+        return False
+
+    # bypass
+    if risk == "destructive" or policy.get("destructive"):
+        return False
+    if sandbox == "system" and tool_name not in COMPUTER_OBSERVATION_TOOLS | COMPUTER_CONTROL_TOOLS:
+        # Non-desktop system tools stay gated even in bypass.
+        if risk in {"write", "exec"}:
+            return False
+    return True
+
+
+def should_stage_proposal(
+    mode: PermissionMode | str,
+    *,
+    proposal_required: bool,
+) -> bool:
+    """Whether mutation/destructive file changes should become Review proposals.
+
+    * strict  — yes (proposal-first, current behaviour)
+    * trusted — no for mutations (auto-apply + audit); destructive still blocked
+      upstream so this only affects mutation proposals
+    * bypass  — no
+    """
+    if not proposal_required:
+        return False
+    mode = normalize_mode(mode)
+    return mode == PermissionMode.STRICT
+
+
+def plan_requires_approval(
+    mode: PermissionMode | str,
+    *,
+    non_auto_steps: list,
+    plan_flag: bool = False,
+) -> bool:
+    """Plan-level gate used by SingleAgentRuntime.approval_requirements."""
+    mode = normalize_mode(mode)
+    if mode == PermissionMode.BYPASS:
+        return False
+    if mode == PermissionMode.TRUSTED:
+        # Only steps that remain non-auto under trusted force a plan pause.
+        return bool(non_auto_steps) or bool(plan_flag)
+    return bool(non_auto_steps) or bool(plan_flag)
+
+
+def mode_contract(mode: PermissionMode | str) -> Dict[str, Any]:
+    """Serializable contract for API / agent responses."""
+    mode = normalize_mode(mode)
+    entry = next((m for m in mode_catalog() if m["id"] == mode.value), mode_catalog()[0])
+    return {
+        "mode": mode.value,
+        "label": entry["label"],
+        "label_ko": entry["label_ko"],
+        "risk": entry["risk"],
+        "requires_ack": entry["requires_ack"],
+        "proposal_first": mode == PermissionMode.STRICT,
+        "workspace_writes_auto": mode in {PermissionMode.TRUSTED, PermissionMode.BYPASS},
+        "knowledge_reads_auto": mode in {PermissionMode.TRUSTED, PermissionMode.BYPASS},
+        "exec_auto": mode == PermissionMode.BYPASS,
+        "computer_observation_auto": mode in {PermissionMode.TRUSTED, PermissionMode.BYPASS},
+        "computer_control_auto": mode == PermissionMode.BYPASS,
+        "circuit_breakers": True,
+    }
+
+
+__all__ = [
+    "PermissionMode",
+    "DEFAULT_MODE",
+    "COMPUTER_OBSERVATION_TOOLS",
+    "COMPUTER_CONTROL_TOOLS",
+    "KNOWLEDGE_READ_TOOLS",
+    "WORKSPACE_WRITE_TOOLS",
+    "normalize_mode",
+    "mode_catalog",
+    "is_circuit_breaker",
+    "effective_auto_approve",
+    "should_stage_proposal",
+    "plan_requires_approval",
+    "mode_contract",
+]

package/latticeai/core/project_sessions.py

@@ -0,0 +1,337 @@
+"""Persistent project sessions — the multi-turn project loop (v9.9.6).
+
+A single agent run is well modelled: PLAN → EXECUTE → VERIFY, with a durable
+approval pause and a transcript. What was missing is the loop *above* it —
+"만들고 → 고치고 → 검증하고 → 다시 고치는" work that spans several runs and
+several days. Each run started from a blank workspace picture, so the second
+turn could not see what the first produced, what still failed verification, or
+what was left to do.
+
+A project session is that missing state:
+
+* ``files`` — every artifact the project's runs actually produced;
+* ``todos`` — what is still open (explicit, user- or agent-authored);
+* ``last_verification`` — the most recent honest outcome (never upgraded);
+* ``runs`` — the run history that got there.
+
+Storage mirrors :mod:`latticeai.core.run_store`: one JSON file per session
+under the data dir, atomic replace on write, no new dependencies. Reads are
+fail-open (a corrupt file is skipped, not fatal); writes never break a run —
+a project session is context, not a gate.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import secrets
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.io_utils import atomic_write_json
+from latticeai.core.timeutil import now_iso
+
+LOGGER = logging.getLogger(__name__)
+
+__all__ = ["ProjectSessionStore", "PROJECT_STATUSES"]
+
+# Terminal-ish project states. "active" is the default; "archived" hides a
+# project from the default listing without deleting its history.
+PROJECT_STATUSES = ("active", "archived")
+
+_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
+_MAX_FILES = 200
+_MAX_TODOS = 100
+_MAX_RUNS = 100
+
+
+def _clean(value: Any, limit: int) -> str:
+    return str(value or "").strip()[:limit]
+
+
+class ProjectSessionStore:
+    """JSON-file store for long-running project sessions."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = Path(root)
+
+    # ── paths ────────────────────────────────────────────────────────────
+    def _path(self, session_id: str) -> Optional[Path]:
+        if not _SESSION_ID_RE.match(str(session_id or "")):
+            return None
+        return self._root / f"{session_id}.json"
+
+    def _ensure_root(self) -> None:
+        self._root.mkdir(parents=True, exist_ok=True)
+
+    # ── read ─────────────────────────────────────────────────────────────
+    def _load(self, session_id: str) -> Optional[Dict[str, Any]]:
+        path = self._path(session_id)
+        if path is None or not path.exists():
+            return None
+        try:
+            import json
+
+            with path.open(encoding="utf-8") as handle:
+                data = json.load(handle)
+            return data if isinstance(data, dict) else None
+        except Exception as exc:  # noqa: BLE001 — a bad file is skipped, not fatal
+            LOGGER.warning("project session load failed for %s: %s", session_id, exc)
+            return None
+
+    def get(
+        self,
+        session_id: str,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """One session, scoped. Returns None when it does not exist or is
+        outside the caller's scope — never a partial record."""
+        record = self._load(session_id)
+        if record is None:
+            return None
+        if user_email is not None and record.get("user_email") != user_email:
+            return None
+        if workspace_id is not None and record.get("workspace_id") != workspace_id:
+            return None
+        return record
+
+    def list(
+        self,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        status: str = "active",
+    ) -> Dict[str, Any]:
+        """Sessions for a caller, newest first. ``status="all"`` includes archived."""
+        if not self._root.exists():
+            return {"projects": [], "count": 0}
+        sessions: List[Dict[str, Any]] = []
+        for path in self._root.glob("*.json"):
+            record = self._load(path.stem)
+            if record is None:
+                continue
+            if user_email is not None and record.get("user_email") != user_email:
+                continue
+            if workspace_id is not None and record.get("workspace_id") != workspace_id:
+                continue
+            if status != "all" and record.get("status") != status:
+                continue
+            sessions.append(record)
+        sessions.sort(key=lambda item: str(item.get("updated_at") or ""), reverse=True)
+        return {"projects": sessions, "count": len(sessions)}
+
+    # ── write ────────────────────────────────────────────────────────────
+    def _save(self, record: Dict[str, Any]) -> Dict[str, Any]:
+        record["updated_at"] = now_iso()
+        path = self._path(str(record.get("id") or ""))
+        if path is None:
+            raise ValueError("invalid project session id")
+        try:
+            self._ensure_root()
+            atomic_write_json(path, record)
+        except Exception as exc:  # noqa: BLE001 — persistence never breaks a run
+            LOGGER.warning("project session save failed for %s: %s", record.get("id"), exc)
+        return record
+
+    def create(
+        self,
+        *,
+        title: str,
+        goal: str = "",
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        session_id = secrets.token_urlsafe(12)
+        record = {
+            "id": session_id,
+            "title": _clean(title, 200) or "프로젝트",
+            "goal": _clean(goal, 2000),
+            "status": "active",
+            "user_email": user_email,
+            "workspace_id": workspace_id,
+            "created_at": now_iso(),
+            "updated_at": now_iso(),
+            "files": [],
+            "todos": [],
+            "runs": [],
+            "last_verification": None,
+        }
+        return self._save(record)
+
+    def update(
+        self,
+        session_id: str,
+        *,
+        title: Optional[str] = None,
+        goal: Optional[str] = None,
+        status: Optional[str] = None,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        record = self.get(session_id, user_email=user_email, workspace_id=workspace_id)
+        if record is None:
+            return None
+        if title is not None:
+            record["title"] = _clean(title, 200) or record["title"]
+        if goal is not None:
+            record["goal"] = _clean(goal, 2000)
+        if status is not None and status in PROJECT_STATUSES:
+            record["status"] = status
+        return self._save(record)
+
+    def delete(
+        self,
+        session_id: str,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> bool:
+        record = self.get(session_id, user_email=user_email, workspace_id=workspace_id)
+        if record is None:
+            return False
+        path = self._path(session_id)
+        try:
+            if path is not None and path.exists():
+                path.unlink()
+            return True
+        except OSError as exc:
+            LOGGER.warning("project session delete failed for %s: %s", session_id, exc)
+            return False
+
+    def set_todos(
+        self,
+        session_id: str,
+        todos: List[Any],
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Replace the open-work list. Accepts strings or ``{text, done}`` dicts."""
+        record = self.get(session_id, user_email=user_email, workspace_id=workspace_id)
+        if record is None:
+            return None
+        normalized: List[Dict[str, Any]] = []
+        for raw in list(todos or [])[:_MAX_TODOS]:
+            if isinstance(raw, dict):
+                text = _clean(raw.get("text"), 300)
+                done = bool(raw.get("done"))
+            else:
+                text = _clean(raw, 300)
+                done = False
+            if text:
+                normalized.append({"text": text, "done": done})
+        record["todos"] = normalized
+        return self._save(record)
+
+    def record_run(
+        self,
+        session_id: str,
+        *,
+        run_id: str = "",
+        goal: str = "",
+        status: str = "",
+        final_state: str = "",
+        files: Optional[List[Any]] = None,
+        explanation: Optional[Dict[str, Any]] = None,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Fold one finished agent run into the project's state.
+
+        The verification result is recorded exactly as the run reported it —
+        a NEEDS_REVIEW run never becomes a project's "done".
+        """
+        record = self.get(session_id, user_email=user_email, workspace_id=workspace_id)
+        if record is None:
+            return None
+        paths: List[str] = []
+        for entry in list(files or []):
+            path = entry if isinstance(entry, str) else (entry or {}).get("path")
+            path = _clean(path, 400)
+            if path and path not in paths:
+                paths.append(path)
+        known = list(record.get("files") or [])
+        for path in paths:
+            if path not in known:
+                known.append(path)
+        record["files"] = known[-_MAX_FILES:]
+        headline = ""
+        next_step = ""
+        if isinstance(explanation, dict):
+            headline = _clean((explanation.get("headline") or {}).get("ko"), 400)
+            next_step = _clean((explanation.get("next_step") or {}).get("ko"), 400)
+        entry = {
+            "run_id": _clean(run_id, 120),
+            "goal": _clean(goal, 400),
+            "status": _clean(status, 40),
+            "final_state": _clean(final_state, 40),
+            "files": paths,
+            "at": now_iso(),
+            **({"headline": headline} if headline else {}),
+            **({"next_step": next_step} if next_step else {}),
+        }
+        runs = list(record.get("runs") or [])
+        runs.append(entry)
+        record["runs"] = runs[-_MAX_RUNS:]
+        record["last_verification"] = {
+            "final_state": entry["final_state"],
+            "ok": bool(isinstance(explanation, dict) and explanation.get("ok")),
+            "at": entry["at"],
+            **({"headline": headline} if headline else {}),
+            # Failure-learning loop (review 루프 §3): what the *last* attempt
+            # says to do differently travels into the next run's plan context
+            # instead of dying with the run.
+            **({"next_step": next_step} if next_step else {}),
+        }
+        return self._save(record)
+
+    # ── prompt context ───────────────────────────────────────────────────
+    def summary(
+        self,
+        session_id: str,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        max_files: int = 15,
+        max_todos: int = 10,
+    ) -> str:
+        """Prompt block describing where this project stands.
+
+        Injected into the planner/executor context so a later run sees the
+        files that already exist, what is still open, and whether the last
+        attempt actually passed. Empty string when there is nothing to say —
+        an empty project must not pad the prompt.
+        """
+        record = self.get(session_id, user_email=user_email, workspace_id=workspace_id)
+        if record is None:
+            return ""
+        lines: List[str] = []
+        title = record.get("title") or ""
+        goal = record.get("goal") or ""
+        lines.append(f"Project: {title}" + (f" — {goal}" if goal else ""))
+        files = list(record.get("files") or [])[-max_files:]
+        if files:
+            lines.append("Files this project has already produced (they exist now):")
+            lines.extend(f"- {path}" for path in files)
+        open_todos = [
+            todo for todo in (record.get("todos") or []) if not todo.get("done")
+        ][:max_todos]
+        if open_todos:
+            lines.append("Still open:")
+            lines.extend(f"- {todo['text']}" for todo in open_todos)
+        verification = record.get("last_verification")
+        if isinstance(verification, dict) and verification.get("final_state"):
+            verdict = verification["final_state"]
+            headline = verification.get("headline") or ""
+            lines.append(
+                f"Last verification: {verdict}" + (f" — {headline}" if headline else "")
+            )
+            next_step = verification.get("next_step") or ""
+            if next_step and not verification.get("ok"):
+                # The previous attempt's own diagnosis, so this plan does not
+                # repeat the same failure.
+                lines.append(f"What the last attempt said to do differently: {next_step}")
+        # Only the header line means nothing worth injecting.
+        return "\n".join(lines) if len(lines) > 1 else ""