ltcai 11.2.0 → 11.4.0

package/latticeai/core/agent/planning.py

@@ -0,0 +1,145 @@
+"""PLAN and APPROVAL — deciding what to do, and whether it may be done.
+
+The planner turns the request into a structured plan; the approval gate then
+answers one question about that plan under the run's autonomy dial: does a step
+in it need a human to say yes? :meth:`approval_requirements` is the read-only
+half of exactly the predicate :meth:`approve` enforces, so the HTTP layer can
+pause a run instead of failing it closed without ever weakening the gate.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from latticeai.core.agent_helpers import extract_action_details, normalize_plan
+from latticeai.core.agent_permission import non_auto_plan_steps
+from latticeai.core.agent_state import AgentState
+from latticeai.core.permission_mode import plan_requires_approval
+
+from ._contract import AgentCore as _Core
+from .context import AgentRunContext
+
+
+class _PlanningMixin(_Core):
+    """The PLAN and APPROVAL phases of :class:`SingleAgentRuntime`."""
+
+    # ── PLAN ─────────────────────────────────────────────────────────
+    async def plan(
+        self, ctx: AgentRunContext, req: Any, lang_hint: str, current_user: str,
+        model_id: Optional[str] = None,
+    ) -> None:
+        """PLAN: Planner role produces a structured plan JSON."""
+        d = self.deps
+        project_block = self._project_block(ctx)
+        context = (
+            f"{d.planner_prompt}\n\n"
+            f"[LANGUAGE HINT: {lang_hint}]\n"
+            f"Workspace root: {d.agent_root}{project_block}\n\n"
+            f"User request: {req.message}"
+        )
+        raw = await d.generate_as(
+            model_id,
+            message="Produce a JSON execution plan for this request.",
+            context=context, max_tokens=self.phase_budgets.plan_tokens, temperature=0.1,
+        )
+        ctx.trace.llm_call("plan", model=model_id)
+        try:
+            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": [],
+                "requires_approval": False, "rollback_strategy": "none", "estimated_steps": 1,
+            }
+        plan, plan_fixes = normalize_plan(plan, req.message)
+        if plan_fixes:
+            ctx.trace.repair("plan", repairs=plan_fixes)
+        ctx.plan = plan
+        ctx.transcript.append({
+            "state": AgentState.PLANNING.value,
+            "goal": plan.get("goal", req.message),
+            "steps": plan.get("steps", []),
+            "requires_approval": plan.get("requires_approval", False),
+            "rollback_strategy": plan.get("rollback_strategy", "none"),
+            "estimated_steps": plan.get("estimated_steps", 1),
+            **({"plan_fixes": plan_fixes} if plan_fixes else {}),
+        })
+        self._emit_step(
+            ctx, "plan", "planned",
+            goal=str(plan.get("goal") or "")[:200],
+            steps=len(plan.get("steps") or []),
+            requires_approval=bool(plan.get("requires_approval", False)),
+        )
+        ctx.state = AgentState.WAITING_APPROVAL
+
+    # ── APPROVAL ─────────────────────────────────────────────────────
+    def approval_requirements(self, ctx: AgentRunContext) -> Dict[str, Any]:
+        """Read-only preview of the approval gate for a planned run.
+
+        Shares the exact predicate :meth:`approve` enforces, so the HTTP
+        layer can pause a run as ``awaiting_approval`` (with a plan summary
+        for the user) instead of letting it fail closed — without ever
+        weakening the gate itself.
+        """
+        d = self.deps
+        mode = self.resolve_permission_mode(ctx)
+        # 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 = self._governed_tools()
+        steps = ctx.plan.get("steps", [])
+        non_auto = non_auto_plan_steps(
+            mode, steps, d.tool_governance or {}, governed_tools=governed_tools,
+        )
+        requires = plan_requires_approval(
+            mode,
+            non_auto_steps=non_auto,
+            plan_flag=bool(ctx.plan.get("requires_approval", False)),
+        )
+        lines = [
+            f"{index}. {step.get('description') or step.get('action') or '?'}"
+            for index, step in enumerate(steps, start=1)
+        ]
+        summary = str(ctx.plan.get("goal") or "").strip()
+        if lines:
+            summary = (summary + "\n" if summary else "") + "\n".join(lines)
+        return {
+            "requires_approval": requires,
+            "non_auto_steps": non_auto,
+            "permission_mode": mode.value,
+            "plan_summary": summary,
+        }
+
+    def approve(self, ctx: AgentRunContext, current_user: str, *, approved_by_human: bool = False) -> None:
+        """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
+        d = self.deps
+        requirements = self.approval_requirements(ctx)
+        non_auto = requirements["non_auto_steps"]
+        requires = requirements["requires_approval"]
+
+        ctx.transcript.append({
+            "state": AgentState.WAITING_APPROVAL.value,
+            "requires_approval": requires,
+            "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))
+        self._emit_step(ctx, "approval", "decision", decision=decision)
+        d.audit(
+            "agent_approval", user_email=current_user,
+            requires_approval=requires,
+            non_auto_steps=non_auto,
+            decision=decision,
+        )
+        if requires and not approved_by_human:
+            ctx.final_message = (
+                "이 작업에는 명시 승인이 필요한 도구가 포함되어 있어 자동 실행을 중단했습니다. "
+                "human_in_loop 승인 흐름으로 다시 실행해 주세요."
+            )
+            ctx.state = AgentState.FAILED
+            return
+        ctx.approved_by_human = bool(approved_by_human)
+        ctx.state = AgentState.EXECUTING

package/latticeai/core/agent/recovery.py

@@ -0,0 +1,157 @@
+"""ROLLBACK and MEMORY — putting the workspace back, and keeping the lesson.
+
+Recovery tries git first where the policy says the tool is git-rollbackable,
+then the pre-write snapshot the executor captured, and otherwise reports
+``mode="none"`` rather than claiming a recovery it did not perform. The memory
+phase records what a *terminal* run taught: DONE runs record what worked,
+FAILED and NEEDS_REVIEW runs record what went wrong, stored under the run's
+actual terminal state and never a blanket "ok".
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.agent_helpers import extract_action, filter_learnings
+from latticeai.core.agent_state import AGENT_TERMINAL_STATES, AgentState
+
+from ._contract import AgentCore as _Core
+from .context import AgentRunContext
+
+
+class _RecoveryMixin(_Core):
+    """The ROLLBACK and MEMORY phases of :class:`SingleAgentRuntime`."""
+
+    # ── ROLLBACK ─────────────────────────────────────────────────────
+    def _snapshot_for(self, ctx: AgentRunContext, path: str) -> Optional[Dict[str, Any]]:
+        for entry in ctx.rollback_log:
+            if entry.get("path") == path:
+                return entry
+        return None
+
+    def _rollback_one(self, ctx: AgentRunContext, path: str, gov: Dict[str, Any]) -> Dict[str, Any]:
+        """Recover one path: git when governed and available, else the
+        pre-write snapshot, else an honest ``mode="none"`` (review L7)."""
+        d = self.deps
+        if gov.get("rollback") == "git" and d.rollback_file is not None:
+            try:
+                result = dict(d.rollback_file(str(path)))
+            except Exception as exc:  # noqa: BLE001
+                result = {"path": path, "ok": False, "error": str(exc)}
+            if result.get("ok"):
+                result["mode"] = "git"
+                return result
+        snapshot = self._snapshot_for(ctx, str(path))
+        if snapshot is not None and d.restore_snapshot is not None and not snapshot.get("too_large"):
+            content = snapshot.get("content") if snapshot.get("existed") else None
+            try:
+                restored = dict(d.restore_snapshot(str(path), content))
+            except Exception as exc:  # noqa: BLE001
+                restored = {"path": path, "ok": False, "error": str(exc)}
+            restored.setdefault("path", path)
+            restored["mode"] = "snapshot"
+            return restored
+        return {
+            "path": path, "ok": False, "mode": "none",
+            "error": "no rollback available (git not applicable, no usable snapshot)",
+        }
+
+    def rollback(self, ctx: AgentRunContext, current_user: str) -> None:
+        """ROLLBACK: recover written files (git → snapshot → none), then FAILED."""
+        d = self.deps
+        rolled: List[dict] = []
+        seen_paths: set = set()
+        for step in ctx.transcript:
+            if step.get("state") != AgentState.EXECUTING.value:
+                continue
+            if not isinstance(step.get("result"), dict):
+                continue
+            gov = step.get("governance", {}) or {}
+            path = step["result"].get("path") or (step.get("args") or {}).get("path", "")
+            if not path or str(path) in seen_paths:
+                continue
+            if gov.get("rollback") != "git" and step.get("action") not in d.file_create_actions:
+                continue
+            seen_paths.add(str(path))
+            rolled.append(self._rollback_one(ctx, str(path), gov))
+
+        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 = [f"{r['path']} ({r.get('mode')})" for r in rolled if r.get("ok")]
+        ctx.final_message = (
+            f"실행 실패로 롤백했습니다. 복구 파일: {recovered}"
+            if recovered
+            else "롤백을 시도했으나 복구할 파일이 없거나 git/스냅샷 복구 수단이 없습니다."
+        )
+        d.audit("agent_rollback", user_email=current_user, rolled_back=rolled)
+        self._emit_step(ctx, "rollback", "rolled_back", recovered=len(recovered))
+        # Rollback is a recovery from a failed verification — terminal state is FAILED
+        ctx.state = AgentState.FAILED
+
+    # ── MEMORY ───────────────────────────────────────────────────────
+    async def memory_update(self, ctx: AgentRunContext, req: Any, current_user: str) -> None:
+        """Background: Memory Updater role extracts learnings from a terminal run.
+
+        Terminal-state learning policy (review §4.2 L6): DONE runs record what
+        worked; FAILED / NEEDS_REVIEW runs record what went wrong — failure is
+        exactly the experience worth remembering. The run status stored with
+        the experience is the *actual* terminal state, never a blanket "ok".
+        """
+        d = self.deps
+        terminal = ctx.state.value if ctx.state in AGENT_TERMINAL_STATES else "UNKNOWN"
+        outcome_hint = (
+            "The task completed successfully."
+            if ctx.state == AgentState.DONE
+            else (
+                f"The task ended as {terminal} — extract what went wrong and "
+                "what to do differently next time, not a success story."
+            )
+        )
+        context = (
+            f"{d.memory_updater_prompt}\n\n"
+            f"Task: {req.message}\n"
+            f"Terminal status: {terminal}. {outcome_hint}\n\n"
+            f"Last 5 transcript steps:\n{json.dumps(ctx.transcript[-5:], ensure_ascii=False)}"
+        )
+        try:
+            raw = await d.generate(
+                message="Extract learnings from this completed task.",
+                context=context, max_tokens=self.phase_budgets.memory_tokens, temperature=0.1,
+            )
+            mem = extract_action(str(raw))
+            kept_learnings = filter_learnings(mem.get("learnings") or [])
+            if mem.get("save_to_knowledge") and kept_learnings:
+                learnings = "\n".join(kept_learnings)
+                status_label = {
+                    AgentState.DONE: "ok",
+                    AgentState.NEEDS_REVIEW: "needs_review",
+                    AgentState.FAILED: "failed",
+                }.get(ctx.state, "unknown")
+                if d.brain_memory is not None:
+                    # This runtime is LLM-driven — its learnings are real
+                    # experiences and enter the brain with provenance.
+                    d.brain_memory.record_experience(
+                        f"Agent: {req.message[:60]}",
+                        learnings,
+                        run={
+                            "mode": "llm",
+                            "status": status_label,
+                            "agent_id": "agent:executor",
+                            "steps": len(ctx.transcript),
+                        },
+                        user_email=current_user or None,
+                    )
+                else:
+                    d.knowledge_save(
+                        learnings,
+                        folder="30_Projects",
+                        title=f"Agent: {req.message[:60]}",
+                    )
+        except Exception as exc:
+            # Never crash a completed run, but never swallow silently either.
+            logging.warning("agent memory update failed: %s", exc)

package/latticeai/core/agent/runtime.py

@@ -0,0 +1,210 @@
+"""The runtime itself: shared state, the budgets, and the drive loop.
+
+:class:`SingleAgentRuntime` is assembled from the four phase mixins. What lives
+*here* is what all four need — the injected ports, the per-phase token and
+transcript budgets, the autonomy dial, the step observer, the boundary/config
+contracts — plus :meth:`run_to_completion`, which drives EXECUTING → VERIFYING
+→ ROLLBACK until a terminal state.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, FrozenSet, Optional
+
+from lattice_brain.runtime.contracts import (
+    runtime_boundary_contract,
+    single_agent_contract,
+)
+from latticeai.core.agent_helpers import PhaseBudgets, TranscriptBudget
+from latticeai.core.agent_permission import resolve_deps_mode
+from latticeai.core.agent_profiles import AgentProfile, profile_for_model
+from latticeai.core.agent_state import AGENT_TERMINAL_STATES, AgentState
+from latticeai.core.permission_mode import PermissionMode
+from latticeai.tools import document_output_target
+
+from .context import AgentRunContext
+from .deps import AgentDeps
+from .execution import _ExecutionMixin
+from .planning import _PlanningMixin
+from .recovery import _RecoveryMixin
+from .verification import _VerificationMixin
+
+
+class SingleAgentRuntime(
+    _PlanningMixin, _ExecutionMixin, _VerificationMixin, _RecoveryMixin
+):
+    """Drives the agent state machine over injected :class:`AgentDeps`.
+
+    The four mixins define disjoint method sets, so resolution order changes
+    nothing at runtime: this class exposes exactly the methods it exposed when
+    all four phases lived in one 1,465-line module.
+    """
+
+    def __init__(self, deps: AgentDeps) -> None:
+        self.deps = deps
+        self._env_phase_budgets: Optional[PhaseBudgets] = None
+        self._env_transcript_budget: Optional[TranscriptBudget] = None
+
+    @property
+    def phase_budgets(self) -> PhaseBudgets:
+        # getattr twice: partially-constructed runtimes/deps (tests build them
+        # via __new__ or minimal fakes) still get working default budgets.
+        injected = getattr(self.deps, "phase_budgets", None)
+        if injected is not None:
+            return injected
+        cached = getattr(self, "_env_phase_budgets", None)
+        if cached is None:
+            cached = PhaseBudgets.from_env()
+            self._env_phase_budgets = cached
+        return cached
+
+    @property
+    def transcript_budget(self) -> TranscriptBudget:
+        injected = getattr(self.deps, "transcript_budget", None)
+        if injected is not None:
+            return injected
+        cached = getattr(self, "_env_transcript_budget", None)
+        if cached is None:
+            cached = TranscriptBudget.from_env()
+            self._env_transcript_budget = cached
+        return cached
+
+    # ── permission mode (v9.9.8) ─────────────────────────────────────
+    def resolve_permission_mode(
+        self,
+        ctx: Optional[AgentRunContext] = None,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> PermissionMode:
+        """Autonomy dial for this run.
+
+        A mode stamped on ``ctx`` wins, so the plan a user approved and every
+        tool step in the same run are judged by one dial even if the stored
+        preference changes mid-run. Otherwise the resolver on ``deps`` is
+        consulted with the caller's scope — resolving unscoped would collapse
+        every caller onto the process-wide default.
+        """
+        return resolve_deps_mode(
+            self.deps, ctx, user_email=user_email, workspace_id=workspace_id,
+        )
+
+    def _governed_path_exists(self, name: str, path: str) -> bool:
+        """Does this tool call's *real* target already exist?
+
+        The document creators sanitize ``filename`` into their own output
+        directory, so the raw argument is resolved through
+        :func:`document_output_target` first — checking it verbatim would
+        inspect a path nothing ever writes and the fail-closed overwrite guard
+        would never fire. Workspace-relative paths resolve under
+        ``deps.agent_root``; absolute paths (home-sandbox writes) are honored
+        as-is. Never raises: governance must not be able to crash the loop, and
+        an unresolvable path degrades to "new file", which the remaining gates
+        still cover.
+        """
+        try:
+            candidate = Path(document_output_target(name, path) or path)
+            if not candidate.is_absolute():
+                candidate = Path(self.deps.agent_root) / candidate
+            return candidate.exists()
+        except Exception:  # noqa: BLE001 — classification is best-effort
+            return False
+
+    def _governed_tools(self) -> FrozenSet[str]:
+        governor = getattr(self.deps, "change_governor", None)
+        if governor is None:
+            return frozenset()
+        return frozenset(getattr(governor, "governed_tools", frozenset()))
+
+    def profile_for(self, model_id: Optional[str]) -> AgentProfile:
+        """Loop profile for the model actually executing this run (v9.9.7).
+
+        An injected ``AgentDeps.agent_profile`` wins (tests, explicit config);
+        otherwise the profile is derived from the model id, so a small local
+        model gets the compact loop without any extra configuration.
+        """
+        injected = getattr(self.deps, "agent_profile", None)
+        if injected is not None:
+            return injected
+        return profile_for_model(model_id)
+
+    def _emit_step(self, ctx: AgentRunContext, phase: str, event: str, **details: Any) -> None:
+        """Fire the per-run / deps step observers (review Wave 1.1).
+
+        Observers power the live step timeline in the UI. They are pure
+        telemetry: any observer failure is logged and swallowed — the loop
+        itself must never notice.
+        """
+        payload: Dict[str, Any] = {"phase": phase, "event": event}
+        for key, value in details.items():
+            if value is not None:
+                payload[key] = value
+        for observer in (getattr(ctx, "on_step", None), getattr(self.deps, "on_step", None)):
+            if observer is None:
+                continue
+            try:
+                observer(dict(payload))
+            except Exception as exc:  # noqa: BLE001 — observers are advisory
+                logging.warning("agent step observer failed: %s", exc)
+
+    @staticmethod
+    def _project_block(ctx: AgentRunContext) -> str:
+        """Project-session context for prompts, or "" for a standalone run.
+
+        Multi-turn project loop (v9.9.6): a later run must see the files the
+        project already produced and what is still open, instead of planning
+        from a blank workspace every time.
+        """
+        summary = str(getattr(ctx, "project_context", "") or "").strip()
+        return f"\n\n[PROJECT SESSION]\n{summary}" if summary else ""
+
+    def boundary(self) -> Dict[str, Any]:
+        return runtime_boundary_contract(
+            name="SingleAgentRuntime",
+            runtime="single_agent",
+            entrypoint="latticeai.core.agent.SingleAgentRuntime",
+            surface="/agent",
+            owns="single-agent PLAN / EXECUTE / VERIFY state machine over injected ports",
+            compatibility_aliases=[],
+        )
+
+    def config(self) -> Dict[str, Any]:
+        return {
+            "boundary": self.boundary(),
+            "states": [state.value for state in AgentState],
+            "terminal_states": sorted(state.value for state in AGENT_TERMINAL_STATES),
+            "execution_mode": "injected_ports",
+        }
+
+    def contract(self, ctx: AgentRunContext, req: Any, *, run_id: Optional[str] = None) -> Dict[str, Any]:
+        """Expose the shared agent-run contract for the single-agent loop."""
+        return single_agent_contract(ctx=ctx, goal=getattr(req, "message", ""), run_id=run_id)
+
+    # ── DRIVE LOOP ───────────────────────────────────────────────────
+    async def run_to_completion(
+        self, ctx: AgentRunContext, req: Any, lang_hint: str,
+        current_user: str, max_steps: int, max_retry: int,
+    ) -> None:
+        """Run EXECUTING → VERIFYING → ROLLBACK loop until a terminal state."""
+        while ctx.state not in AGENT_TERMINAL_STATES:
+            ctx.state_history.append(ctx.state.value)
+            if len(ctx.state_history) > 200:
+                ctx.final_message = "에이전트 상태 머신이 최대 반복(200)에 도달해 중단했습니다."
+                ctx.state = AgentState.FAILED
+                break
+
+            if ctx.state == AgentState.EXECUTING:
+                await self.execute(ctx, req, lang_hint, current_user, max_steps,
+                                   model_id=ctx.executing_model)
+            elif ctx.state == AgentState.VERIFYING:
+                await self.verify(ctx, req, lang_hint, current_user, max_retry,
+                                  model_id=ctx.reviewing_model)
+            elif ctx.state == AgentState.ROLLBACK:
+                self.rollback(ctx, current_user)
+            else:
+                ctx.state = AgentState.FAILED
+
+        ctx.state_history.append(ctx.state.value)
+        self._emit_step(ctx, "terminal", "state", state=ctx.state.value)