ltcai 9.9.2 → 9.9.3

package/latticeai/app_factory.py

@@ -395,6 +395,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     INGESTION_PIPELINE = _persistence_runtime["INGESTION_PIPELINE"]
     DEVICE_IDENTITY = _persistence_runtime["DEVICE_IDENTITY"]
     KG_PORTABILITY = _persistence_runtime["KG_PORTABILITY"]
+    FUNNEL_METRICS = _persistence_runtime["FUNNEL_METRICS"]
 
     def _require_graph():
         if not ENABLE_GRAPH or KNOWLEDGE_GRAPH is None:
@@ -951,6 +952,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         public_model=PUBLIC_MODEL,
         local_model=LOCAL_MODEL or "",
         on_chat_message=on_chat_message,
+        funnel_metrics=FUNNEL_METRICS,
     )
     app.state.context = context
 
@@ -1036,6 +1038,17 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
             gate_write=PLATFORM.gate_write,
             append_audit_event=append_audit_event,
             workspace_graph=_workspace_graph,
+            run_executor=RUN_EXECUTOR,
+            review_queue=REVIEW_QUEUE,
+        )
+    )
+    # UX funnel metrics (backlog #16): admin-only runtime counters.
+    from latticeai.api.funnel_metrics import create_funnel_metrics_router
+
+    app.include_router(
+        create_funnel_metrics_router(
+            service=FUNNEL_METRICS,
+            require_admin=require_admin,
         )
     )
     COMMAND_CENTER = CommandCenterService(
@@ -1212,6 +1225,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         gardener=gardener,
         create_setup_router=create_setup_router,
         model_router=router,
+        knowledge_graph=KNOWLEDGE_GRAPH,
     )
 
     # ── Entry Point ────────────────────────────────────────────────────────────────

package/latticeai/core/agent.py

@@ -27,7 +27,7 @@ import re
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Optional, Tuple
+from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Mapping, Optional, Tuple
 
 from lattice_brain.runtime.hooks import dispatch_tool
 from lattice_brain.runtime.contracts import runtime_boundary_contract, single_agent_contract
@@ -227,6 +227,44 @@ def filter_learnings(learnings: List[Any]) -> List[str]:
     return kept
 
 
+@dataclass(frozen=True)
+class PhaseBudgets:
+    """Per-phase token budgets for the agent loop.
+
+    One shared budget let a weak model burn everything on planning prose and
+    reach EXECUTE with nothing left. Each role phase now has its own cap, so
+    a verbose planner can never starve execution or verification. Defaults
+    match the historical hardcoded values; every cap is overridable through
+    the ``Config.from_env`` environment pattern.
+    """
+
+    plan_tokens: int = 1024
+    execute_tokens: int = 4096
+    verify_tokens: int = 512
+    memory_tokens: int = 256
+
+    @classmethod
+    def from_env(cls, env: Optional[Mapping[str, str]] = None) -> "PhaseBudgets":
+        from latticeai.core.config import _int
+
+        if env is None:
+            import os
+
+            env = os.environ
+
+        def cap(key: str, default: int) -> int:
+            # A misconfigured/absurd value must not brick the loop: floor at a
+            # budget that still fits one JSON action object.
+            return max(128, _int(env, key, default))
+
+        return cls(
+            plan_tokens=cap("LATTICEAI_AGENT_PLAN_TOKENS", cls.plan_tokens),
+            execute_tokens=cap("LATTICEAI_AGENT_EXECUTE_TOKENS", cls.execute_tokens),
+            verify_tokens=cap("LATTICEAI_AGENT_VERIFY_TOKENS", cls.verify_tokens),
+            memory_tokens=cap("LATTICEAI_AGENT_MEMORY_TOKENS", cls.memory_tokens),
+        )
+
+
 @dataclass
 class AgentDeps:
     """The ports a :class:`SingleAgentRuntime` needs from the outside world.
@@ -286,12 +324,29 @@ class AgentDeps:
     # returning None (fall through to the classic gates) or a verdict dict.
     change_governor: Any = None
 
+    # ── phase budgets (optional) ─────────────────────────────────────
+    # Per-phase token caps (plan/execute/verify/memory). None reads the
+    # environment once at first use; tests inject a fixed PhaseBudgets.
+    phase_budgets: Optional[PhaseBudgets] = None
+
 
 class SingleAgentRuntime:
     """Drives the agent state machine over injected :class:`AgentDeps`."""
 
     def __init__(self, deps: AgentDeps) -> None:
         self.deps = deps
+        self._env_phase_budgets: Optional[PhaseBudgets] = 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
+        if getattr(self, "_env_phase_budgets", None) is None:
+            self._env_phase_budgets = PhaseBudgets.from_env()
+        return self._env_phase_budgets
 
     def boundary(self) -> Dict[str, Any]:
         return runtime_boundary_contract(
@@ -331,7 +386,7 @@ class SingleAgentRuntime:
         raw = await d.generate_as(
             model_id,
             message="Produce a JSON execution plan for this request.",
-            context=context, max_tokens=1024, temperature=0.1,
+            context=context, max_tokens=self.phase_budgets.plan_tokens, temperature=0.1,
         )
         ctx.trace.llm_call("plan", model=model_id)
         try:
@@ -360,8 +415,14 @@ class SingleAgentRuntime:
         ctx.state = AgentState.WAITING_APPROVAL
 
     # ── APPROVAL ─────────────────────────────────────────────────────
-    def approve(self, ctx: AgentRunContext, current_user: str, *, approved_by_human: bool = False) -> None:
-        """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
+    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
         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
@@ -377,7 +438,26 @@ class SingleAgentRuntime:
             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)
+        requires = bool(ctx.plan.get("requires_approval", False)) or bool(non_auto)
+        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,
+            "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,
@@ -420,7 +500,8 @@ class SingleAgentRuntime:
             raw = await d.generate_as(
                 model_id,
                 message="Execute the next step.",
-                context=context, max_tokens=4096, temperature=req.temperature,
+                context=context, max_tokens=self.phase_budgets.execute_tokens,
+                temperature=req.temperature,
             )
             ctx.trace.llm_call("execute", model=model_id)
             try:
@@ -727,7 +808,7 @@ class SingleAgentRuntime:
         raw = await d.generate_as(
             model_id,
             message="Review the execution transcript and return your verdict JSON.",
-            context=context, max_tokens=512, temperature=0.1,
+            context=context, max_tokens=self.phase_budgets.verify_tokens, temperature=0.1,
         )
         ctx.trace.llm_call("verify", model=model_id)
         verdict: Optional[Dict[str, Any]] = None
@@ -749,7 +830,8 @@ class SingleAgentRuntime:
             raw = await d.generate_as(
                 model_id,
                 message="Return your verdict as one strict JSON object.",
-                context=strict_context, max_tokens=512, temperature=0.0,
+                context=strict_context, max_tokens=self.phase_budgets.verify_tokens,
+                temperature=0.0,
             )
             ctx.trace.llm_call("verify", model=model_id)
             try:
@@ -899,7 +981,7 @@ class SingleAgentRuntime:
         try:
             raw = await d.generate(
                 message="Extract learnings from this completed task.",
-                context=context, max_tokens=256, temperature=0.1,
+                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 [])

package/latticeai/core/agent_eval.py

@@ -163,6 +163,18 @@ class Scenario:
     # canned results (node ids, snippets, proposal ids), so an answer that is
     # not grounded in the retrieved/executed evidence fails the scenario.
     expect_final_contains: List[str] = field(default_factory=list)
+    # Exact per-name counts against the LoopTrace ``repairs`` histogram —
+    # filegen scenarios use this to prove the ArtifactWritePipeline actually
+    # fired (``artifact_sanitize`` / ``artifact_repair``), not merely that
+    # the tool ran.
+    expect_repairs: Dict[str, int] = field(default_factory=dict)
+    # Content-level assertions on what file-writing tools actually received
+    # AFTER sanitize: every ``contains`` needle must appear in at least one
+    # written payload, every ``excludes`` needle in none. This is the teeth
+    # of the dirty-write scenarios — a fence or chat wrapper reaching the
+    # tool port fails the gate.
+    expect_write_contains: List[str] = field(default_factory=list)
+    expect_write_excludes: List[str] = field(default_factory=list)
     max_steps: int = 8
 
 
@@ -247,6 +259,37 @@ _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"}'
 
+# ── dirty write_file payloads (ArtifactWritePipeline scenarios) ──────────
+# What weak local models actually put in args.content: chat framing + a
+# Markdown fence around the document. The JSON envelope itself is valid —
+# the dirt is *inside* the content string, so only the write-side sanitize
+# pass (agent.py _dispatch_step → sanitize_write_content) can clean it.
+_DIRTY_HTML_CONTENT = (
+    "Sure! Here is your page:\\n"
+    "```html\\n"
+    "<!DOCTYPE html>\\n<html>\\n<head><meta charset=\\\"utf-8\\\">"
+    "<title>Hello</title></head>\\n<body><h1>Hello</h1></body>\\n</html>\\n"
+    "```\\n"
+    "Hope this helps! Let me know if you need changes."
+)
+_DIRTY_WRITE = (
+    '{"thoughts": "produce the page", "action": "write_file", '
+    '"args": {"path": "pages/hello.html", "content": "' + _DIRTY_HTML_CONTENT + '"}}'
+)
+# Token-limit casualty: the document just stops mid-body (no </body>/</html>).
+_TRUNCATED_HTML_CONTENT = (
+    "<!DOCTYPE html>\\n<html>\\n<head><meta charset=\\\"utf-8\\\">"
+    "<title>Weekly</title></head>\\n<body>\\n<h1>Weekly report</h1>"
+)
+_TRUNCATED_WRITE = (
+    '{"thoughts": "write the report", "action": "write_file", '
+    '"args": {"path": "reports/weekly.html", "content": "' + _TRUNCATED_HTML_CONTENT + '"}}'
+)
+_FILEGEN_PLAN = (
+    '{"action": "plan", "goal": "save the requested web page to disk", '
+    '"steps": [{"action": "write_file"}]}'
+)
+
 
 def default_scenarios() -> List[Scenario]:
     return [
@@ -551,6 +594,54 @@ def default_scenarios() -> List[Scenario]:
             expected_class="failed",
             expect_tool_outcomes={"error": 1},
         ),
+        # ── ArtifactWritePipeline (write-side sanitize) ─────────────────
+        Scenario(
+            name="filegen-dirty-write-sanitized-critic-pass",
+            # Weak model wraps args.content in prose + a Markdown fence. The
+            # sanitize pass must strip the wrapper BEFORE the tool runs, the
+            # trace must record artifact_sanitize, and the critic PASS then
+            # completes over a transcript whose written payload is clean.
+            replies=[_FILEGEN_PLAN, _DIRTY_WRITE, _FINAL, _PASS],
+            expect_exact={"parse_errors": 0},
+            expect_tool_outcomes={"ok": 1},
+            expect_tool_calls=["write_file"],
+            expect_repairs={"artifact_sanitize": 1},
+            expect_write_contains=["<!DOCTYPE html>", "</html>"],
+            expect_write_excludes=["```", "Sure!", "Hope this helps"],
+        ),
+        Scenario(
+            name="filegen-truncated-write-repaired-critic-pass",
+            # Token-limit truncation: no extractable clean document exists, so
+            # the pipeline's deterministic repair must close the document
+            # (artifact_repair) — the file on disk is still structurally valid.
+            replies=[_FILEGEN_PLAN, _TRUNCATED_WRITE, _FINAL, _PASS],
+            expect_exact={"parse_errors": 0},
+            expect_tool_outcomes={"ok": 1},
+            expect_tool_calls=["write_file"],
+            expect_repairs={"artifact_repair": 1},
+            expect_write_contains=["<h1>Weekly report</h1>", "</body>", "</html>"],
+            expect_write_excludes=["```"],
+        ),
+        Scenario(
+            name="filegen-dirty-write-unverifiable-needs-review",
+            # The dirty write is sanitized and runs, but the critic never
+            # produces a parseable verdict — fail-closed: the run must end
+            # NEEDS_REVIEW (never a fabricated DONE), while the written file
+            # stays clean because sanitize ran before the tool.
+            replies=[
+                _FILEGEN_PLAN, _DIRTY_WRITE, _FINAL,
+                "the page looks great, approving!",       # unparseable critic
+                "still prose, still not a JSON verdict",  # strict retry fails too
+            ],
+            expect_state="NEEDS_REVIEW",
+            expected_class="needs_review",
+            expect_min={"parse_errors": 2},
+            expect_tool_outcomes={"ok": 1},
+            expect_tool_calls=["write_file"],
+            expect_repairs={"artifact_sanitize": 1},
+            expect_write_excludes=["```", "Sure!"],
+            expect_final_contains=["직접 확인"],
+        ),
     ]
 
 
@@ -591,6 +682,22 @@ async def _run_scenario(scenario: Scenario) -> Dict[str, Any]:
     for needle in scenario.expect_final_contains:
         if needle not in ctx.final_message:
             failures.append(f"final_message missing {needle!r}")
+    for repair_name, count in scenario.expect_repairs.items():
+        seen = int((summary.get("repairs") or {}).get(repair_name, 0))
+        if seen != count:
+            failures.append(f"repairs[{repair_name}]={seen} != {count}")
+    # Payloads the file-writing tools actually received (post-sanitize).
+    written = [
+        str((call.get("args") or {}).get("content") or "")
+        for call in tool_log
+        if call["name"] in ("write_file", "generate_file")
+    ]
+    for needle in scenario.expect_write_contains:
+        if not any(needle in payload for payload in written):
+            failures.append(f"written content missing {needle!r}")
+    for needle in scenario.expect_write_excludes:
+        if any(needle in payload for payload in written):
+            failures.append(f"written content must not contain {needle!r}")
     if governor is not None and summary["tool_outcomes"].get("proposed", 0) != len(governor.proposals):
         failures.append(
             f"governor proposals={len(governor.proposals)} != "