ltcai 9.4.0 → 9.6.0

package/latticeai/core/agent_trace.py

@@ -0,0 +1,104 @@
+"""Structured observability for the single-agent reasoning loop (v9.6.0).
+
+The PLAN → EXECUTE → VERIFY state machine in :mod:`latticeai.core.agent`
+already keeps a human-readable transcript, but the transcript mixes model
+output, tool results, and control decisions into one list — you cannot ask
+"how many parse failures were recovered?" or "which repairs did the weak
+model need?" without re-parsing it.
+
+:class:`LoopTrace` is the machine-readable side channel: every phase records
+typed events (llm_call, parse_error, repair, correction, tool call outcome,
+blocked action, retry, rollback), and :meth:`LoopTrace.summary` reduces them
+to the counters an evaluation harness or the API response can consume
+directly. The trace is pure data — no I/O, no clock dependency beyond an
+injectable timestamp function — so unit tests and the deterministic agent
+evaluation harness can assert on it exactly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from latticeai.core.timeutil import now_iso
+
+_MAX_EVENTS = 500
+
+
+class LoopTrace:
+    """Typed event stream + summary counters for one agent run."""
+
+    def __init__(self, clock: Optional[Callable[[], str]] = None) -> None:
+        self._clock = clock or now_iso
+        self.events: List[Dict[str, Any]] = []
+        self.truncated = 0
+
+    def record(self, phase: str, kind: str, **details: Any) -> None:
+        if len(self.events) >= _MAX_EVENTS:
+            self.truncated += 1
+            return
+        event: Dict[str, Any] = {"phase": phase, "kind": kind, "at": self._clock()}
+        for key, value in details.items():
+            if value is not None:
+                event[key] = value
+        self.events.append(event)
+
+    # ── typed helpers keep call sites terse and the vocabulary closed ────
+
+    def llm_call(self, phase: str, *, model: Optional[str] = None) -> None:
+        self.record(phase, "llm_call", model=model)
+
+    def parse_error(self, phase: str, *, error: str, recovered: bool) -> None:
+        self.record(phase, "parse_error", error=error[:200], recovered=recovered)
+
+    def repair(self, phase: str, *, repairs: List[str]) -> None:
+        if repairs:
+            self.record(phase, "repair", repairs=list(repairs))
+
+    def correction(self, phase: str, *, hint: str) -> None:
+        self.record(phase, "correction", hint=hint[:200])
+
+    def tool(self, phase: str, *, name: str, outcome: str, risk: Optional[str] = None) -> None:
+        self.record(phase, "tool", name=name, outcome=outcome, risk=risk)
+
+    def decision(self, phase: str, *, decision: str, **details: Any) -> None:
+        self.record(phase, "decision", decision=decision, **details)
+
+    def retry(self, phase: str, *, attempt: int) -> None:
+        self.record(phase, "retry", attempt=attempt)
+
+    # ── reduction ────────────────────────────────────────────────────────
+
+    def summary(self) -> Dict[str, Any]:
+        counts: Dict[str, int] = {}
+        tool_outcomes: Dict[str, int] = {}
+        repairs: Dict[str, int] = {}
+        parse_errors = 0
+        parse_recovered = 0
+        for event in self.events:
+            kind = event["kind"]
+            counts[kind] = counts.get(kind, 0) + 1
+            if kind == "tool":
+                outcome = str(event.get("outcome") or "unknown")
+                tool_outcomes[outcome] = tool_outcomes.get(outcome, 0) + 1
+            elif kind == "parse_error":
+                parse_errors += 1
+                if event.get("recovered"):
+                    parse_recovered += 1
+            elif kind == "repair":
+                for name in event.get("repairs") or []:
+                    repairs[name] = repairs.get(name, 0) + 1
+        return {
+            "events": len(self.events),
+            "truncated_events": self.truncated,
+            "kind_counts": counts,
+            "llm_calls": counts.get("llm_call", 0),
+            "parse_errors": parse_errors,
+            "parse_recovered": parse_recovered,
+            "corrections": counts.get("correction", 0),
+            "retries": counts.get("retry", 0),
+            "tool_outcomes": tool_outcomes,
+            "repairs": repairs,
+        }
+
+
+__all__ = ["LoopTrace"]

package/latticeai/core/legacy_compatibility.py

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

package/latticeai/core/marketplace.py

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

package/latticeai/core/tool_governor.py

@@ -0,0 +1,101 @@
+"""Central change-class governor for tool calls (v9.6.0).
+
+The tool registry already answers "how risky is this tool?" (read / write /
+exec, destructive, auto-approve). What it could not answer is the question
+users actually care about: **does this call create something new, or does it
+change/remove something that already exists?**
+
+The governor adds that dimension in one place:
+
+* ``read`` — no state change.
+* ``additive`` — creates new content only (new file, new note, new node).
+  Low friction: runs under the existing gates without extra ceremony.
+* ``mutation`` — rewrites existing content (overwrite / edit of an existing
+  file). Proposal-first: instead of applying silently, the change is staged
+  as a review proposal the user merges deliberately.
+* ``destructive`` — removes existing content. Always proposal-first.
+
+Classification is deterministic and injectable (``path_exists``), so the
+agent loop, the chat file path, and tests all share exactly one policy.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Mapping, Optional
+
+CHANGE_READ = "read"
+CHANGE_ADDITIVE = "additive"
+CHANGE_MUTATION = "mutation"
+CHANGE_DESTRUCTIVE = "destructive"
+CHANGE_EXEC = "exec"
+
+# Tools whose effect depends on whether the target already exists.
+_TARGET_WRITE_TOOLS = frozenset({
+    "write_file", "local_write",
+    "create_docx", "create_xlsx", "create_pptx", "create_pdf",
+})
+# Tools that always rewrite existing content.
+_ALWAYS_MUTATION_TOOLS = frozenset({"edit_file"})
+# Tools that remove existing content.
+_DESTRUCTIVE_TOOLS = frozenset({"delete_file", "remove_file", "clear_history"})
+# Additive-only knowledge writes (append-style, never rewrite).
+_ADDITIVE_TOOLS = frozenset({
+    "knowledge_save", "obsidian_save", "todo_write", "create_web_project",
+    "knowledge_graph_ingest",
+})
+
+
+def classify_tool_call(
+    name: str,
+    args: Mapping[str, Any],
+    *,
+    policy: Optional[Mapping[str, Any]] = None,
+    path_exists: Optional[Callable[[str], bool]] = None,
+) -> Dict[str, Any]:
+    """Classify one tool call into a change class + proposal requirement."""
+    risk = str((policy or {}).get("risk") or "")
+    change = CHANGE_READ
+    reason = "read-only tool"
+
+    if name in _DESTRUCTIVE_TOOLS or (policy or {}).get("destructive"):
+        change = CHANGE_DESTRUCTIVE
+        reason = "removes existing content"
+    elif name in _ALWAYS_MUTATION_TOOLS:
+        change = CHANGE_MUTATION
+        reason = "edits existing content in place"
+    elif name in _TARGET_WRITE_TOOLS:
+        path = str(args.get("path") or args.get("filename") or "")
+        exists = bool(path and path_exists and path_exists(path))
+        change = CHANGE_MUTATION if exists else CHANGE_ADDITIVE
+        reason = (
+            "overwrites an existing file" if exists else "creates a new file"
+        )
+    elif name in _ADDITIVE_TOOLS:
+        change = CHANGE_ADDITIVE
+        reason = "adds new content only"
+    elif risk.startswith("read"):
+        change = CHANGE_READ
+        reason = "read-only tool"
+    elif risk == "exec":
+        change = CHANGE_EXEC
+        reason = "executes an action (approval-gated, not proposal-based)"
+    elif risk in {"write", "write_scoped"}:
+        change = CHANGE_ADDITIVE
+        reason = "write tool without an existing target"
+
+    return {
+        "tool": name,
+        "change_class": change,
+        "proposal_required": change in {CHANGE_MUTATION, CHANGE_DESTRUCTIVE},
+        "reason": reason,
+    }
+
+
+__all__ = [
+    "CHANGE_READ",
+    "CHANGE_ADDITIVE",
+    "CHANGE_MUTATION",
+    "CHANGE_DESTRUCTIVE",
+    "CHANGE_EXEC",
+    "classify_tool_call",
+]

package/latticeai/core/workspace_os.py

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

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.4.0"
+ARCHITECTURE_VERSION_TARGET = "9.6.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/change_proposals.py

@@ -0,0 +1,270 @@
+"""Change proposals — 수정/삭제는 제안으로, 생성은 바로 (v9.6.0).
+
+The consent model most users actually want is git's: creating something new
+is cheap and reversible, but changing or deleting what already exists
+deserves a review. This service implements that model for the agent
+workspace:
+
+* **additive** operations (new files, new notes) run with minimal friction;
+* **mutation/destructive** operations (overwrite, in-place edit, delete of
+  an existing file) are *staged as proposals* instead of applied: a review
+  item (source ``change_proposal``) carrying the target path, a unified
+  diff, the exact resulting content, and a small/large tier. Nothing changes
+  on disk until the user approves; rejecting discards the staged change.
+
+Approving applies the staged content exactly as reviewed (never recomputed),
+then marks the review item approved — so the review timeline doubles as the
+change audit log. The classification itself lives in
+:mod:`latticeai.core.tool_governor` so every entry point shares one policy.
+"""
+
+from __future__ import annotations
+
+import difflib
+import logging
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from latticeai.core.tool_governor import classify_tool_call
+
+LOGGER = logging.getLogger(__name__)
+
+_MAX_STAGED_BYTES = 400_000
+_MAX_DIFF_LINES = 400
+_SMALL_TIER_DIFF_LINES = 40
+
+
+def _unified_diff(before: str, after: str, path: str) -> List[str]:
+    lines = list(
+        difflib.unified_diff(
+            before.splitlines(), after.splitlines(),
+            fromfile=f"a/{path}", tofile=f"b/{path}", lineterm="",
+        )
+    )
+    return lines[:_MAX_DIFF_LINES]
+
+
+class ChangeProposalService:
+    """Stages mutation/destructive file changes as reviewable proposals."""
+
+    #: Tools whose plan-time approval is delegated to per-call governance.
+    governed_tools = frozenset({"write_file", "edit_file"})
+
+    def __init__(
+        self,
+        *,
+        review_queue: Any,
+        resolve_path: Callable[[str], Path],
+        audit: Optional[Callable[..., None]] = None,
+    ) -> None:
+        self._review_queue = review_queue
+        self._resolve_path = resolve_path
+        self._audit = audit or (lambda *a, **kw: None)
+
+    # ── classification / staging (agent-loop governor port) ─────────────
+
+    def review(
+        self,
+        name: str,
+        args: Dict[str, Any],
+        *,
+        policy: Optional[Dict[str, Any]] = None,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Governor port for the agent loop.
+
+        Returns ``None`` to fall through to the existing gates, or a verdict:
+        ``{"decision": "allow_additive"}`` (execute without extra approval) /
+        ``{"decision": "proposed", "proposal": {...}}`` (staged for review).
+        """
+        if name not in {"write_file", "edit_file"}:
+            return None
+        verdict = classify_tool_call(
+            name, args, policy=policy, path_exists=self._path_exists
+        )
+        if verdict["change_class"] == "additive":
+            return {"decision": "allow_additive", "classification": verdict}
+        if not verdict["proposal_required"]:
+            return None
+
+        path = str(args.get("path") or "")
+        after = self._staged_content(name, args)
+        if after is None:
+            # The edit cannot be computed deterministically (e.g. old_string
+            # not found) — let the normal tool path surface the real error.
+            return None
+        try:
+            proposal = self.propose_file_update(
+                path=path,
+                new_content=after,
+                proposed_by="agent",
+                reason=verdict["reason"],
+                user_email=user_email,
+                workspace_id=workspace_id,
+            )
+        except Exception:
+            LOGGER.exception("change proposal staging failed")
+            return None
+        return {"decision": "proposed", "classification": verdict, "proposal": proposal}
+
+    def _path_exists(self, path: str) -> bool:
+        try:
+            return self._resolve_path(path).is_file()
+        except Exception:
+            return False
+
+    def _read_before(self, path: str) -> str:
+        try:
+            target = self._resolve_path(path)
+            if not target.is_file():
+                return ""
+            raw = target.read_bytes()[:_MAX_STAGED_BYTES]
+            return raw.decode("utf-8", errors="replace")
+        except Exception:
+            LOGGER.exception("change proposal read failed")
+            return ""
+
+    def _staged_content(self, name: str, args: Dict[str, Any]) -> Optional[str]:
+        if name == "write_file":
+            return str(args.get("content") or "")[:_MAX_STAGED_BYTES]
+        if name == "edit_file":
+            before = self._read_before(str(args.get("path") or ""))
+            old = str(args.get("old_string") or "")
+            new = str(args.get("new_string") or "")
+            if not old or old not in before:
+                return None
+            if args.get("replace_all"):
+                return before.replace(old, new)[:_MAX_STAGED_BYTES]
+            if before.count(old) != 1:
+                return None
+            return before.replace(old, new, 1)[:_MAX_STAGED_BYTES]
+        return None
+
+    # ── proposal creation ────────────────────────────────────────────────
+
+    def propose_file_update(
+        self,
+        *,
+        path: str,
+        new_content: str,
+        proposed_by: str = "agent",
+        reason: str = "",
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        before = self._read_before(path)
+        diff = _unified_diff(before, new_content, path)
+        tier = "small" if len(diff) <= _SMALL_TIER_DIFF_LINES else "large"
+        item = self._review_queue.create(
+            title=f"파일 수정 제안: {path}",
+            summary=reason or "기존 파일을 변경하는 작업이라 검토 후 적용됩니다.",
+            source="change_proposal",
+            kind="file_update",
+            payload={
+                "path": path,
+                "diff": diff,
+                "new_content": new_content[:_MAX_STAGED_BYTES],
+                "tier": tier,
+                "before_bytes": len(before.encode("utf-8")),
+                "after_bytes": len(new_content.encode("utf-8")),
+            },
+            provenance={"proposed_by": proposed_by, "reason": reason},
+            user_email=user_email,
+            workspace_id=workspace_id,
+        )
+        self._audit(
+            "change_proposal_created", user_email=user_email,
+            proposal_id=item.get("id"), path=path, kind="file_update", tier=tier,
+        )
+        return item
+
+    def propose_file_delete(
+        self,
+        *,
+        path: str,
+        proposed_by: str = "agent",
+        reason: str = "",
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        before = self._read_before(path)
+        item = self._review_queue.create(
+            title=f"파일 삭제 제안: {path}",
+            summary=reason or "기존 파일을 삭제하는 작업이라 검토 후 적용됩니다.",
+            source="change_proposal",
+            kind="file_delete",
+            payload={
+                "path": path,
+                "diff": _unified_diff(before, "", path),
+                "tier": "large",
+                "before_bytes": len(before.encode("utf-8")),
+                "after_bytes": 0,
+            },
+            provenance={"proposed_by": proposed_by, "reason": reason},
+            user_email=user_email,
+            workspace_id=workspace_id,
+        )
+        self._audit(
+            "change_proposal_created", user_email=user_email,
+            proposal_id=item.get("id"), path=path, kind="file_delete", tier="large",
+        )
+        return item
+
+    # ── listing / apply / reject ─────────────────────────────────────────
+
+    def pending(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        listed = self._review_queue.list(
+            workspace_id=workspace_id, user_email=user_email,
+            status="pending", source="change_proposal",
+        )
+        items = listed.get("items") or []
+        return {
+            "items": items,
+            "count": len(items),
+            "contract": {
+                "additive_writes": "auto",
+                "mutations": "proposal",
+                "deletions": "proposal",
+                "applied_content": "exactly_as_reviewed",
+            },
+        }
+
+    def approve_and_apply(
+        self, item_id: str, *, user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        item = self._review_queue.get(item_id, workspace_id=workspace_id)
+        payload = item.get("payload") or {}
+        kind = item.get("kind")
+        path = str(payload.get("path") or "")
+        target = self._resolve_path(path)
+        if kind == "file_update":
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(str(payload.get("new_content") or ""), encoding="utf-8")
+        elif kind == "file_delete":
+            if target.is_file():
+                target.unlink()
+        else:
+            raise ValueError(f"unknown change proposal kind: {kind}")
+        approved = self._review_queue.approve(item_id, workspace_id=workspace_id)
+        self._audit(
+            "change_proposal_applied", user_email=user_email,
+            proposal_id=item_id, path=path, kind=kind,
+        )
+        return {"item": approved, "applied": True, "path": path, "kind": kind}
+
+    def reject(
+        self, item_id: str, *, user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
+        self._audit(
+            "change_proposal_rejected", user_email=user_email, proposal_id=item_id,
+        )
+        return {"item": dismissed, "applied": False}
+
+
+__all__ = ["ChangeProposalService"]