ltcai 11.5.2 → 11.6.0

package/latticeai/core/agent/planning.py

@@ -1,145 +0,0 @@
-"""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

@@ -1,157 +0,0 @@
-"""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

@@ -1,210 +0,0 @@
-"""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)