ltcai 9.5.0 → 9.7.0

package/latticeai/core/agent.py

@@ -20,16 +20,18 @@ only owns the state machine.
 
 from __future__ import annotations
 
+import ast
 import json
 import logging
 import re
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Optional
+from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Optional, Tuple
 
 from lattice_brain.runtime.hooks import dispatch_tool
 from lattice_brain.runtime.contracts import runtime_boundary_contract, single_agent_contract
+from latticeai.core.agent_trace import LoopTrace
 from latticeai.core.tool_registry import SCOPED_KNOWLEDGE_TOOLS
 from latticeai.tools import ToolError
 
@@ -53,10 +55,11 @@ class AgentRunContext:
     """Mutable state carrier passed through all agent phases."""
     __slots__ = ("state", "plan", "transcript", "retry_count",
                  "state_history", "corrections", "final_message", "rollback_log",
-                 "executing_model", "reviewing_model", "approved_by_human")
+                 "executing_model", "reviewing_model", "approved_by_human", "trace")
 
     def __init__(self) -> None:
         self.state:           AgentState   = AgentState.IDLE
+        self.trace:           LoopTrace    = LoopTrace()
         self.plan:            dict         = {}
         self.transcript:      list         = []
         self.retry_count:     int          = 0
@@ -74,20 +77,31 @@ _THINK_BLOCK_RE = re.compile(
 )
 
 
-def extract_action(raw: str) -> Dict:
-    """Parse one JSON action object out of an LLM response (tolerant of fences/prose)."""
+def extract_action_details(raw: str) -> Tuple[Dict, List[str]]:
+    """Parse one JSON action object out of an LLM response (tolerant of fences/prose).
+
+    Returns ``(action, repairs)`` where ``repairs`` names every tolerance that
+    was needed — the loop trace and the weak-model robustness harness consume
+    it to measure how much help a given model needs.
+    """
+    repairs: List[str] = []
     # Small local models often prepend <think>...</think> reasoning that can
     # itself contain braces — drop it before locating the action object.
     text = _THINK_BLOCK_RE.sub("", raw).strip()
+    if text != str(raw).strip():
+        repairs.append("think_strip")
     fenced = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, flags=re.DOTALL)
     if fenced:
         text = fenced.group(1).strip()
+        repairs.append("fence")
     elif not text.startswith("{"):
         start = text.find("{")
         end = text.rfind("}")
         if start >= 0 and end > start:
             text = text[start : end + 1]
+            repairs.append("slice")
 
+    action: Any = None
     try:
         action = json.loads(text)
     except json.JSONDecodeError:
@@ -96,11 +110,28 @@ def extract_action(raw: str) -> Dict:
         repaired = re.sub(r",\s*([}\]])", r"\1", text)
         try:
             action = json.loads(repaired)
+            repairs.append("trailing_comma")
         except json.JSONDecodeError as exc:
-            raise ValueError(f"Agent did not return valid JSON: {exc}") from exc
+            # Last chance: weak models sometimes emit a Python dict literal
+            # (single quotes, True/False/None). ast.literal_eval parses that
+            # deterministically without evaluating code.
+            try:
+                literal = ast.literal_eval(text)
+            except (ValueError, SyntaxError):
+                raise ValueError(f"Agent did not return valid JSON: {exc}") from exc
+            if not isinstance(literal, dict):
+                raise ValueError(f"Agent did not return valid JSON: {exc}") from exc
+            action = literal
+            repairs.append("python_literal")
 
     if not isinstance(action, dict) or "action" not in action:
         raise ValueError("Agent JSON must include an action field.")
+    return action, repairs
+
+
+def extract_action(raw: str) -> Dict:
+    """Back-compat wrapper over :func:`extract_action_details`."""
+    action, _ = extract_action_details(raw)
     return action
 
 
@@ -155,6 +186,14 @@ class AgentDeps:
     # the vault markdown dump.
     brain_memory: Any = None
 
+    # ── change governor port (optional) ──────────────────────────────
+    # When present, file writes are classified centrally: additive creates
+    # run with minimal friction, while mutations/deletions of existing
+    # content are staged as review proposals instead of applied. The port is
+    # ``review(name, args, policy=..., user_email=..., workspace_id=...)``
+    # returning None (fall through to the classic gates) or a verdict dict.
+    change_governor: Any = None
+
 
 class SingleAgentRuntime:
     """Drives the agent state machine over injected :class:`AgentDeps`."""
@@ -202,9 +241,12 @@ class SingleAgentRuntime:
             message="Produce a JSON execution plan for this request.",
             context=context, max_tokens=1024, temperature=0.1,
         )
+        ctx.trace.llm_call("plan", model=model_id)
         try:
-            plan = extract_action(str(raw))
-        except ValueError:
+            plan, plan_repairs = extract_action_details(str(raw))
+            ctx.trace.repair("plan", repairs=plan_repairs)
+        except ValueError as exc:
+            ctx.trace.parse_error("plan", error=str(exc), recovered=True)
             plan = {
                 "action": "plan", "state": "PLAN",
                 "goal": req.message, "steps": [],
@@ -226,8 +268,19 @@ class SingleAgentRuntime:
         """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
         d = self.deps
         auto_approve_tools = {name for name, p in d.tool_governance.items() if p["auto_approve"]}
+        # Governor-managed tools never hard-block the plan: each call is
+        # classified at execution time — additive creates run, mutations and
+        # deletions of existing content become review proposals.
+        governed_tools = (
+            frozenset(getattr(d.change_governor, "governed_tools", frozenset()))
+            if d.change_governor is not None else frozenset()
+        )
         steps = ctx.plan.get("steps", [])
-        non_auto = [s.get("action") for s in steps if s.get("action") not in auto_approve_tools]
+        non_auto = [
+            s.get("action") for s in steps
+            if s.get("action") not in auto_approve_tools
+            and s.get("action") not in governed_tools
+        ]
         requires = ctx.plan.get("requires_approval", False) or bool(non_auto)
 
         ctx.transcript.append({
@@ -236,11 +289,13 @@ class SingleAgentRuntime:
             "non_auto_approve_steps": non_auto,
             "decision": "human_approved" if requires and approved_by_human else ("blocked_pending_approval" if requires else "auto_approved"),
         })
+        decision = "human_approved" if requires and approved_by_human else ("blocked_pending_approval" if requires else "auto_approved")
+        ctx.trace.decision("approve", decision=decision, non_auto_steps=len(non_auto))
         d.audit(
             "agent_approval", user_email=current_user,
             requires_approval=requires,
             non_auto_steps=non_auto,
-            decision="human_approved" if requires and approved_by_human else ("blocked_pending_approval" if requires else "auto_approved"),
+            decision=decision,
         )
         if requires and not approved_by_human:
             ctx.final_message = (
@@ -264,53 +319,21 @@ class SingleAgentRuntime:
         parse_failures = 0
 
         for _ in range(budget):
-            corrections_hint = (
-                "\n\nCritic corrections from previous attempt:\n"
-                + "\n".join(f"- {c}" for c in ctx.corrections)
-            ) if ctx.corrections else ""
-
             request_workspace = getattr(req, "workspace_id", None)
-            recent_kwargs = {
-                "conversation_id": req.conversation_id,
-                "user_email": current_user or None,
-            }
-            if request_workspace is not None:
-                recent_kwargs["workspace_id"] = request_workspace
-            recent_conversation = d.recent_chat_context(**recent_kwargs) or "(none)"
-            context = (
-                f"{d.executor_prompt}\n\n"
-                f"[LANGUAGE HINT: {lang_hint}]\n"
-                f"Workspace root: {d.agent_root}\n\n"
-                f"PLAN:\n{json.dumps(ctx.plan, ensure_ascii=False)}\n\n"
-                f"Recent conversation:\n{recent_conversation}\n\n"
-                f"User request: {req.message}{corrections_hint}\n\n"
-                f"Execution transcript:\n{json.dumps(ctx.transcript, ensure_ascii=False, indent=2)}"
-            )
+            context = self._executor_context(ctx, req, lang_hint, current_user, request_workspace)
             raw = await d.generate_as(
                 model_id,
                 message="Execute the next step.",
                 context=context, max_tokens=4096, temperature=req.temperature,
             )
+            ctx.trace.llm_call("execute", model=model_id)
             try:
-                action = extract_action(str(raw))
+                action, exec_repairs = extract_action_details(str(raw))
+                ctx.trace.repair("execute", repairs=exec_repairs)
             except ValueError as exc:
                 parse_failures += 1
-                ctx.transcript.append({
-                    "state": AgentState.EXECUTING.value, "action": "parse_error",
-                    "raw": str(raw)[:400], "error": str(exc),
-                })
-                if parse_failures >= 3:
+                if self._note_parse_failure(ctx, raw, exc, parse_failures):
                     break
-                # Weak models often need one concrete reminder of the wire
-                # format; feed it through the corrections channel and retry
-                # instead of aborting the whole run on the first slip.
-                hint = (
-                    'Your last reply was not a single JSON action object. Reply with '
-                    'EXACTLY one JSON object like {"thoughts": "...", "action": '
-                    '"tool_name", "args": {...}} and nothing else.'
-                )
-                if hint not in ctx.corrections:
-                    ctx.corrections.append(hint)
                 continue
 
             name     = action.get("action")
@@ -329,22 +352,17 @@ class SingleAgentRuntime:
                 ctx.transcript.append({
                     "state": AgentState.EXECUTING.value, "action": "final", "thoughts": thoughts,
                 })
+                ctx.trace.decision("execute", decision="final")
                 ctx.state = AgentState.VERIFYING
                 return
 
             # Loop guard
-            exec_steps = [s for s in ctx.transcript if s.get("state") == AgentState.EXECUTING.value]
-            last = exec_steps[-1] if exec_steps else None
-            if (
-                name in d.file_create_actions and last
-                and last.get("action") == name
-                and (last.get("args") or {}) == args
-                and "result" in last
-            ):
+            if self._is_repeated_create(ctx, name, args):
                 ctx.transcript.append({
                     "state": AgentState.EXECUTING.value, "action": name,
                     "error": "LOOP_DETECTED: identical action+args repeated — halted.",
                 })
+                ctx.trace.decision("execute", decision="loop_detected", tool=name)
                 break
 
             if name == "clear_history":
@@ -358,58 +376,203 @@ class SingleAgentRuntime:
             policy = d.policy_for(name, args)
             risk   = d.risk_level(policy)
 
-            if policy["risk"] == "destructive":
-                ctx.transcript.append({
-                    "state": AgentState.EXECUTING.value, "action": name,
-                    "thoughts": thoughts, "args": args, "risk": risk,
-                    "governance": dict(policy),
-                    "error": f"BLOCKED: destructive action '{name}' not permitted in agent mode.",
-                })
-                d.audit(
-                    "agent_blocked", user_email=current_user, source=getattr(req, "source", None) or "agent",
-                    action=name, reason="destructive", governance=dict(policy),
-                )
+            proposed, governor_allows_additive = self._governor_review(
+                ctx, name, thoughts, args, policy, risk, current_user, request_workspace,
+                conversation_id=getattr(req, "conversation_id", None),
+            )
+            if proposed:
                 continue
 
-            if not policy["auto_approve"] and not ctx.approved_by_human:
-                d.audit(
-                    "agent_exec", user_email=current_user, source=getattr(req, "source", None) or "agent",
-                    state=AgentState.EXECUTING.value, action=name, risk=risk,
-                    shell=policy["shell"], network=policy["network"],
-                    destructive=policy["destructive"], sandbox=policy["sandbox"],
-                    rollback=policy["rollback"],
-                    args={k: v for k, v in args.items() if k != "content"},
-                )
-                ctx.transcript.append({
-                    "state": AgentState.EXECUTING.value, "action": name,
-                    "thoughts": thoughts, "args": args, "risk": risk,
-                    "governance": dict(policy),
-                    "error": f"BLOCKED: action '{name}' requires explicit approval.",
-                })
+            if self._blocked_by_gates(
+                ctx, req, name, thoughts, args, policy, risk,
+                current_user, governor_allows_additive,
+            ):
                 continue
 
-            try:
-                d.check_role(name, current_user)
-                # Shared tool lifecycle: pre_tool (may block) → execute → post_tool.
-                result = dispatch_tool(
-                    d.hooks, name, args,
-                    lambda: d.execute_tool(name, args),
-                    user_email=current_user, source="agent",
-                )
-                ctx.transcript.append({
-                    "state": AgentState.EXECUTING.value, "action": name,
-                    "thoughts": thoughts, "args": args,
-                    "risk": risk, "governance": dict(policy), "result": result,
-                })
-            except (ToolError, KeyError, TypeError, PermissionError) as exc:
-                ctx.transcript.append({
-                    "state": AgentState.EXECUTING.value, "action": name,
-                    "thoughts": thoughts, "args": args,
-                    "risk": risk, "governance": dict(policy), "error": str(exc),
-                })
+            self._dispatch_step(ctx, name, thoughts, args, policy, risk, current_user)
 
         ctx.state = AgentState.VERIFYING
 
+    def _executor_context(
+        self, ctx: AgentRunContext, req: Any, lang_hint: str,
+        current_user: str, request_workspace: Optional[str],
+    ) -> str:
+        """Assemble one executor turn's prompt (plan, corrections, recent chat)."""
+        d = self.deps
+        corrections_hint = (
+            "\n\nCritic corrections from previous attempt:\n"
+            + "\n".join(f"- {c}" for c in ctx.corrections)
+        ) if ctx.corrections else ""
+
+        recent_kwargs = {
+            "conversation_id": req.conversation_id,
+            "user_email": current_user or None,
+        }
+        if request_workspace is not None:
+            recent_kwargs["workspace_id"] = request_workspace
+        recent_conversation = d.recent_chat_context(**recent_kwargs) or "(none)"
+        return (
+            f"{d.executor_prompt}\n\n"
+            f"[LANGUAGE HINT: {lang_hint}]\n"
+            f"Workspace root: {d.agent_root}\n\n"
+            f"PLAN:\n{json.dumps(ctx.plan, ensure_ascii=False)}\n\n"
+            f"Recent conversation:\n{recent_conversation}\n\n"
+            f"User request: {req.message}{corrections_hint}\n\n"
+            f"Execution transcript:\n{json.dumps(ctx.transcript, ensure_ascii=False, indent=2)}"
+        )
+
+    def _note_parse_failure(
+        self, ctx: AgentRunContext, raw: Any, exc: ValueError, parse_failures: int,
+    ) -> bool:
+        """Record one executor parse slip; True when the run should stop retrying."""
+        ctx.transcript.append({
+            "state": AgentState.EXECUTING.value, "action": "parse_error",
+            "raw": str(raw)[:400], "error": str(exc),
+        })
+        if parse_failures >= 3:
+            ctx.trace.parse_error("execute", error=str(exc), recovered=False)
+            return True
+        ctx.trace.parse_error("execute", error=str(exc), recovered=True)
+        # Weak models often need one concrete reminder of the wire
+        # format; feed it through the corrections channel and retry
+        # instead of aborting the whole run on the first slip.
+        hint = (
+            'Your last reply was not a single JSON action object. Reply with '
+            'EXACTLY one JSON object like {"thoughts": "...", "action": '
+            '"tool_name", "args": {...}} and nothing else.'
+        )
+        if parse_failures >= 2:
+            # Escalate: name the valid tools so the model stops
+            # inventing action names or prose.
+            valid = ", ".join(sorted(self.deps.tool_governance.keys()))
+            hint = (
+                f"{hint} Valid action values are: {valid}, final. "
+                'Use {"action": "final", "message": "..."} to finish.'
+            )
+        if hint not in ctx.corrections:
+            ctx.corrections.append(hint)
+            ctx.trace.correction("execute", hint=hint)
+        return False
+
+    def _is_repeated_create(self, ctx: AgentRunContext, name: Any, args: dict) -> bool:
+        """Loop guard: the same file-create action+args re-issued right after a result."""
+        exec_steps = [s for s in ctx.transcript if s.get("state") == AgentState.EXECUTING.value]
+        last = exec_steps[-1] if exec_steps else None
+        return bool(
+            name in self.deps.file_create_actions and last
+            and last.get("action") == name
+            and (last.get("args") or {}) == args
+            and "result" in last
+        )
+
+    def _governor_review(
+        self, ctx: AgentRunContext, name: str, thoughts: str, args: dict,
+        policy: dict, risk: str, current_user: str, request_workspace: Optional[str],
+        conversation_id: Optional[str] = None,
+    ) -> Tuple[bool, bool]:
+        """Central change-class governance: create-new runs with minimal
+        friction, change/delete-existing becomes a review proposal.
+
+        Returns ``(proposed, governor_allows_additive)``: ``proposed`` means the
+        step was staged as a proposal (skip execution); ``allows_additive`` lets
+        an additive create pass the classic approval gate.
+        """
+        d = self.deps
+        if d.change_governor is None:
+            return False, False
+        verdict = d.change_governor.review(
+            name, args, policy=dict(policy),
+            user_email=current_user, workspace_id=request_workspace,
+            conversation_id=conversation_id,
+        )
+        if verdict is not None and verdict.get("decision") == "proposed":
+            proposal = verdict.get("proposal") or {}
+            ctx.trace.tool("execute", name=name, outcome="proposed", risk=risk)
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": {k: v for k, v in args.items() if k != "content"},
+                "risk": risk, "governance": dict(policy),
+                "result": {
+                    "proposed": True,
+                    "proposal_id": proposal.get("id"),
+                    "note": "기존 내용을 바꾸는 작업이라 변경 제안으로 저장했습니다. 검토함에서 승인하면 적용됩니다.",
+                },
+            })
+            d.audit(
+                "agent_change_proposed", user_email=current_user,
+                action=name, proposal_id=proposal.get("id"),
+                change_class=(verdict.get("classification") or {}).get("change_class"),
+            )
+            return True, False
+        return False, (verdict is not None and verdict.get("decision") == "allow_additive")
+
+    def _blocked_by_gates(
+        self, ctx: AgentRunContext, req: Any, name: str, thoughts: str, args: dict,
+        policy: dict, risk: str, current_user: str, governor_allows_additive: bool,
+    ) -> bool:
+        """Classic destructive / explicit-approval gates; True when the step was blocked."""
+        d = self.deps
+        if policy["risk"] == "destructive":
+            ctx.trace.tool("execute", name=name, outcome="blocked_destructive", risk=risk)
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args, "risk": risk,
+                "governance": dict(policy),
+                "error": f"BLOCKED: destructive action '{name}' not permitted in agent mode.",
+            })
+            d.audit(
+                "agent_blocked", user_email=current_user, source=getattr(req, "source", None) or "agent",
+                action=name, reason="destructive", governance=dict(policy),
+            )
+            return True
+
+        if not policy["auto_approve"] and not ctx.approved_by_human and not governor_allows_additive:
+            d.audit(
+                "agent_exec", user_email=current_user, source=getattr(req, "source", None) or "agent",
+                state=AgentState.EXECUTING.value, action=name, risk=risk,
+                shell=policy["shell"], network=policy["network"],
+                destructive=policy["destructive"], sandbox=policy["sandbox"],
+                rollback=policy["rollback"],
+                args={k: v for k, v in args.items() if k != "content"},
+            )
+            ctx.trace.tool("execute", name=name, outcome="blocked_approval", risk=risk)
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args, "risk": risk,
+                "governance": dict(policy),
+                "error": f"BLOCKED: action '{name}' requires explicit approval.",
+            })
+            return True
+        return False
+
+    def _dispatch_step(
+        self, ctx: AgentRunContext, name: str, thoughts: str, args: dict,
+        policy: dict, risk: str, current_user: str,
+    ) -> None:
+        """Role check + shared tool lifecycle, recorded on the transcript either way."""
+        d = self.deps
+        try:
+            d.check_role(name, current_user)
+            # Shared tool lifecycle: pre_tool (may block) → execute → post_tool.
+            result = dispatch_tool(
+                d.hooks, name, args,
+                lambda: d.execute_tool(name, args),
+                user_email=current_user, source="agent",
+            )
+            ctx.trace.tool("execute", name=name, outcome="ok", risk=risk)
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args,
+                "risk": risk, "governance": dict(policy), "result": result,
+            })
+        except (ToolError, KeyError, TypeError, PermissionError) as exc:
+            ctx.trace.tool("execute", name=name, outcome="error", risk=risk)
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args,
+                "risk": risk, "governance": dict(policy), "error": str(exc),
+            })
+
     # ── VERIFY ───────────────────────────────────────────────────────
     async def verify(
         self, ctx: AgentRunContext, req: Any, lang_hint: str, current_user: str,
@@ -429,9 +592,12 @@ class SingleAgentRuntime:
             message="Review the execution transcript and return your verdict JSON.",
             context=context, max_tokens=512, temperature=0.1,
         )
+        ctx.trace.llm_call("verify", model=model_id)
         try:
-            verdict = extract_action(str(raw))
-        except ValueError:
+            verdict, verdict_repairs = extract_action_details(str(raw))
+            ctx.trace.repair("verify", repairs=verdict_repairs)
+        except ValueError as exc:
+            ctx.trace.parse_error("verify", error=str(exc), recovered=True)
             verdict = {"action": "verdict", "verdict": "PASS", "next_state": "DONE",
                        "reason": "Critic parse failed — assuming pass.", "corrections": [], "confidence": 0.7}
 
@@ -449,6 +615,7 @@ class SingleAgentRuntime:
             "next_state":  next_s,
         })
 
+        ctx.trace.decision("verify", decision=str(verdict.get("verdict", "PASS")), next_state=next_s)
         if verdict.get("verdict") == "PASS" or next_s == "DONE":
             if not ctx.final_message:
                 ctx.final_message = verdict.get("reason", "작업이 완료되었습니다.")
@@ -461,6 +628,7 @@ class SingleAgentRuntime:
                 ctx.state = AgentState.FAILED
             else:
                 ctx.retry_count += 1
+                ctx.trace.retry("verify", attempt=ctx.retry_count)
                 ctx.transcript.append({
                     "state": AgentState.EXECUTING.value,
                     "retry_attempt": ctx.retry_count,
@@ -497,6 +665,10 @@ class SingleAgentRuntime:
                 rolled.append({"path": path, "ok": False, "error": str(exc)})
 
         ctx.transcript.append({"state": AgentState.ROLLBACK.value, "rolled_back": rolled})
+        ctx.trace.decision(
+            "rollback", decision="rolled_back",
+            attempted=len(rolled), recovered=sum(1 for r in rolled if r.get("ok")),
+        )
         recovered = [r["path"] for r in rolled if r.get("ok")]
         ctx.final_message = (
             f"실행 실패로 롤백했습니다. 복구 파일: {recovered}"