ltcai 9.4.0 → 9.6.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 = (
@@ -291,8 +346,10 @@ class SingleAgentRuntime:
                 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({
@@ -300,7 +357,9 @@ class SingleAgentRuntime:
                     "raw": str(raw)[:400], "error": str(exc),
                 })
                 if parse_failures >= 3:
+                    ctx.trace.parse_error("execute", error=str(exc), recovered=False)
                     break
+                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.
@@ -309,8 +368,17 @@ class SingleAgentRuntime:
                     '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(d.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)
                 continue
 
             name     = action.get("action")
@@ -329,6 +397,7 @@ class SingleAgentRuntime:
                 ctx.transcript.append({
                     "state": AgentState.EXECUTING.value, "action": "final", "thoughts": thoughts,
                 })
+                ctx.trace.decision("execute", decision="final")
                 ctx.state = AgentState.VERIFYING
                 return
 
@@ -345,6 +414,7 @@ class SingleAgentRuntime:
                     "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,7 +428,39 @@ class SingleAgentRuntime:
             policy = d.policy_for(name, args)
             risk   = d.risk_level(policy)
 
+            # Central change-class governance: create-new runs with minimal
+            # friction, change/delete-existing becomes a review proposal.
+            governor_allows_additive = False
+            if d.change_governor is not None:
+                verdict = d.change_governor.review(
+                    name, args, policy=dict(policy),
+                    user_email=current_user, workspace_id=request_workspace,
+                )
+                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"),
+                    )
+                    continue
+                governor_allows_additive = (
+                    verdict is not None and verdict.get("decision") == "allow_additive"
+                )
+
             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,
@@ -371,7 +473,7 @@ class SingleAgentRuntime:
                 )
                 continue
 
-            if not policy["auto_approve"] and not ctx.approved_by_human:
+            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,
@@ -380,6 +482,7 @@ class SingleAgentRuntime:
                     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,
@@ -396,12 +499,14 @@ class SingleAgentRuntime:
                     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,
@@ -429,9 +534,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 +557,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 +570,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 +607,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}"

package/latticeai/core/agent_eval.py

@@ -0,0 +1,260 @@
+"""Deterministic agent-loop evaluation harness (v9.6.0).
+
+The Brain has a safety harness (governance, approval gates, audit) but until
+9.6.0 no *evaluation* harness: nothing measured whether the reasoning loop
+actually completes tasks, recovers from weak-model formatting slips, or
+respects its guards. This module closes that gap without any model:
+
+* every scenario scripts the exact model replies (including the malformed
+  outputs small local models really produce — think blocks, Python dict
+  literals, trailing commas, prose) and drives the real
+  :class:`~latticeai.core.agent.SingleAgentRuntime` state machine over fake
+  ports;
+* expectations are asserted against the loop's own :class:`LoopTrace`
+  summary, so the harness measures the same observability surface the API
+  exposes;
+* the result is a scoreboard (`scenarios`, `passed`, `success_rate`,
+  aggregate recovery stats) consumed by ``scripts/agent_eval.py`` as a
+  release gate.
+
+Deterministic by construction: no model, no network, no filesystem writes
+(the tool port records calls in memory).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+from latticeai.core.agent import (
+    AgentDeps,
+    AgentRunContext,
+    AgentState,
+    SingleAgentRuntime,
+)
+
+_AUTO_POLICY = {
+    "auto_approve": True, "risk": "low", "shell": False, "network": False,
+    "destructive": False, "sandbox": False, "rollback": "none",
+}
+_DESTRUCTIVE_POLICY = {
+    "auto_approve": False, "risk": "destructive", "shell": True, "network": False,
+    "destructive": True, "sandbox": False, "rollback": "none",
+}
+
+
+@dataclass
+class Scenario:
+    """One scripted conversation through the real agent state machine."""
+
+    name: str
+    replies: List[str]
+    expect_state: str = "DONE"
+    # Each key is compared against the LoopTrace summary with >= / == / <=
+    expect_min: Dict[str, int] = field(default_factory=dict)
+    expect_exact: Dict[str, Any] = field(default_factory=dict)
+    expect_tool_outcomes: Dict[str, int] = field(default_factory=dict)
+    max_steps: int = 8
+
+
+class _Req:
+    conversation_id = None
+    temperature = 0.2
+    workspace_id = None
+    source = "agent_eval"
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+
+def _build_deps(replies: List[str], tool_log: List[Dict[str, Any]]) -> AgentDeps:
+    queue = list(replies)
+
+    async def generate_as(model_id, message, context, max_tokens, temperature):
+        if not queue:
+            # A scenario that exhausts its script means the loop asked for
+            # more turns than expected — end it deterministically.
+            return '{"action": "verdict", "verdict": "PASS", "next_state": "DONE", "reason": "script exhausted"}'
+        return queue.pop(0)
+
+    async def generate(**kwargs):
+        return '{"action": "noop"}'
+
+    def execute_tool(name: str, args: dict) -> dict:
+        tool_log.append({"name": name, "args": args})
+        return {"ok": True, "path": args.get("path", "")}
+
+    def policy_for(name: str, args: dict) -> dict:
+        if name == "delete_everything":
+            return dict(_DESTRUCTIVE_POLICY)
+        return dict(_AUTO_POLICY)
+
+    return AgentDeps(
+        generate_as=generate_as,
+        generate=generate,
+        execute_tool=execute_tool,
+        policy_for=policy_for,
+        risk_level=lambda p: p["risk"],
+        check_role=lambda name, user: None,
+        tool_governance={
+            "write_file": dict(_AUTO_POLICY),
+            "read_file": dict(_AUTO_POLICY),
+            "delete_everything": dict(_DESTRUCTIVE_POLICY),
+        },
+        file_create_actions=frozenset({"write_file"}),
+        recent_chat_context=lambda **kw: "",
+        clear_history=lambda keep: {"ok": True},
+        knowledge_save=lambda *a, **kw: None,
+        audit=lambda *a, **kw: None,
+        planner_prompt="plan", executor_prompt="exec", critic_prompt="critic",
+        memory_updater_prompt="mem", agent_root=Path("/tmp/agent-eval"),
+    )
+
+
+_PLAN = '{"action": "plan", "goal": "task", "steps": [{"action": "write_file"}]}'
+_WRITE = '{"action": "write_file", "args": {"path": "note.txt", "content": "hi"}}'
+_FINAL = '{"action": "final", "message": "done"}'
+_PASS = '{"action": "verdict", "verdict": "PASS", "next_state": "DONE", "reason": "ok"}'
+
+
+def default_scenarios() -> List[Scenario]:
+    return [
+        Scenario(
+            name="happy-path",
+            replies=[_PLAN, _WRITE, _FINAL, _PASS],
+            expect_exact={"parse_errors": 0},
+            expect_tool_outcomes={"ok": 1},
+        ),
+        Scenario(
+            name="weak-model-format-gauntlet",
+            replies=[
+                "<think>let me plan</think>```json\n" + _PLAN + "\n```",
+                "Sure! Here is the action:\n" + _WRITE,
+                "{'action': 'final', 'message': 'done', 'happy': True}",
+                '{"action": "verdict", "verdict": "PASS", "next_state": "DONE",}',
+            ],
+            expect_exact={"parse_errors": 0},
+            expect_min={"llm_calls": 4},
+            expect_tool_outcomes={"ok": 1},
+        ),
+        Scenario(
+            name="prose-slip-recovers-with-correction",
+            replies=[_PLAN, "I will now write the file for you.", _WRITE, _FINAL, _PASS],
+            expect_min={"parse_errors": 1, "parse_recovered": 1, "corrections": 1},
+            expect_tool_outcomes={"ok": 1},
+        ),
+        Scenario(
+            name="double-slip-escalates-tool-list",
+            replies=[
+                _PLAN,
+                "chatty non-json reply",
+                "another chatty reply",
+                _WRITE,
+                _FINAL,
+                _PASS,
+            ],
+            expect_min={"parse_errors": 2, "corrections": 2},
+            expect_tool_outcomes={"ok": 1},
+        ),
+        Scenario(
+            name="destructive-action-blocked",
+            replies=[
+                _PLAN,
+                '{"action": "delete_everything", "args": {}}',
+                _FINAL,
+                _PASS,
+            ],
+            expect_tool_outcomes={"blocked_destructive": 1},
+        ),
+        Scenario(
+            name="identical-action-loop-detected",
+            replies=[_PLAN, _WRITE, _WRITE, _PASS],
+            expect_tool_outcomes={"ok": 1},
+            expect_min={"llm_calls": 4},
+        ),
+        Scenario(
+            name="critic-retry-then-done",
+            replies=[
+                _PLAN,
+                _WRITE,
+                _FINAL,
+                '{"action": "verdict", "verdict": "FAIL", "next_state": "EXECUTING", "corrections": ["also mention the date"]}',
+                _FINAL,
+                _PASS,
+            ],
+            expect_min={"retries": 1},
+        ),
+        Scenario(
+            name="unrecoverable-garbage-still-terminates",
+            replies=[_PLAN, "garbage", "more garbage", "still garbage", _PASS],
+            expect_state="DONE",
+            expect_min={"parse_errors": 3},
+            expect_exact={"tool_outcomes": {}},
+        ),
+    ]
+
+
+async def _run_scenario(scenario: Scenario) -> Dict[str, Any]:
+    tool_log: List[Dict[str, Any]] = []
+    deps = _build_deps(scenario.replies, tool_log)
+    runtime = SingleAgentRuntime(deps)
+    ctx = AgentRunContext()
+    ctx.state = AgentState.PLANNING
+    req = _Req("agent eval task")
+
+    await runtime.plan(ctx, req, "en", "eval@local")
+    runtime.approve(ctx, "eval@local")
+    if ctx.state == AgentState.EXECUTING:
+        await runtime.run_to_completion(
+            ctx, req, "en", "eval@local", max_steps=scenario.max_steps, max_retry=2
+        )
+
+    summary = ctx.trace.summary()
+    failures: List[str] = []
+    if ctx.state.value != scenario.expect_state:
+        failures.append(f"state={ctx.state.value} expected={scenario.expect_state}")
+    for key, minimum in scenario.expect_min.items():
+        if int(summary.get(key) or 0) < minimum:
+            failures.append(f"{key}={summary.get(key)} < {minimum}")
+    for key, exact in scenario.expect_exact.items():
+        if summary.get(key) != exact:
+            failures.append(f"{key}={summary.get(key)} != {exact}")
+    for outcome, count in scenario.expect_tool_outcomes.items():
+        if summary["tool_outcomes"].get(outcome, 0) != count:
+            failures.append(
+                f"tool_outcomes[{outcome}]={summary['tool_outcomes'].get(outcome, 0)} != {count}"
+            )
+    return {
+        "name": scenario.name,
+        "ok": not failures,
+        "failures": failures,
+        "final_state": ctx.state.value,
+        "summary": summary,
+        "tool_calls": len(tool_log),
+    }
+
+
+def run_agent_eval(scenarios: List[Scenario] | None = None) -> Dict[str, Any]:
+    """Run every scenario and reduce to a release-gate scoreboard."""
+
+    async def _run_all() -> List[Dict[str, Any]]:
+        return [await _run_scenario(s) for s in (scenarios or default_scenarios())]
+
+    results = asyncio.run(_run_all())
+    passed = [r for r in results if r["ok"]]
+    total_parse_errors = sum(r["summary"]["parse_errors"] for r in results)
+    total_recovered = sum(r["summary"]["parse_recovered"] for r in results)
+    return {
+        "scenarios": len(results),
+        "passed": len(passed),
+        "success_rate": round(len(passed) / len(results), 4) if results else 0.0,
+        "parse_errors": total_parse_errors,
+        "parse_recovered": total_recovered,
+        "recovery_rate": round(total_recovered / total_parse_errors, 4) if total_parse_errors else 1.0,
+        "results": results,
+    }
+
+
+__all__ = ["Scenario", "default_scenarios", "run_agent_eval"]