ltcai 11.5.2 → 11.7.0

package/latticeai/core/realtime.py

@@ -1,238 +0,0 @@
-"""Realtime Collaboration — an in-process pub/sub bus, presence registry, and
-activity feed delivered over Server-Sent Events.
-
-SSE is chosen deliberately: the codebase already streams model output over SSE
-(``latticeai.services.model_runtime.sse_event``), it needs no extra dependency,
-and it works through the existing single-port local-first deployment. The bus is
-in-process (one server, local-first) and fans events out to subscriber queues.
-
-Integration shape: the Workspace OS store exposes a single ``event_sink`` hook
-that fires on every ``record_timeline_event``. Wiring ``RealtimeBus.publish`` as
-that sink makes *all* workspace / graph / agent / workflow activity flow into
-the realtime feed automatically — no per-call instrumentation, no duplicated
-event system.
-
-Guarantees:
-
-* **Single-user local mode keeps working.** Publishing with zero subscribers is
-  a no-op; the feed ring buffer is still maintained so a late subscriber can
-  catch up.
-* **Workspace isolation preserved.** Every event carries ``workspace_id``; a
-  subscriber only receives events whose workspace is in its allowed scope set
-  (``None`` scope = personal/local view sees unscoped + personal events).
-* **Backpressure-safe.** Per-subscriber queues are bounded; on overflow the
-  oldest event is dropped rather than blocking the publisher.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import threading
-from typing import Any, AsyncIterator, Callable, Dict, List, Optional, Set
-
-from lattice_brain.runtime.contracts import realtime_event_contract
-from latticeai.core.quiet import quiet
-
-from .timeutil import now_iso as _now
-
-REALTIME_VERSION = "2.2.0"
-_FEED_LIMIT = 200
-_QUEUE_MAX = 100
-
-
-def sse_format(event: Dict[str, Any]) -> str:
-    """Encode an event as an SSE ``data:`` frame."""
-    return f"data: {json.dumps(event, ensure_ascii=False, default=str)}\n\n"
-
-
-class _Subscriber:
-    __slots__ = ("id", "queue", "workspace_scope", "user", "joined_at", "loop")
-
-    def __init__(self, sub_id: str, workspace_scope: Optional[Set[str]], user: Optional[str]):
-        self.id = sub_id
-        self.queue: "asyncio.Queue[Dict[str, Any]]" = asyncio.Queue(maxsize=_QUEUE_MAX)
-        self.workspace_scope = workspace_scope
-        self.user = user
-        self.joined_at = _now()
-        try:
-            self.loop: Optional[asyncio.AbstractEventLoop] = asyncio.get_running_loop()
-        except RuntimeError:
-            self.loop = None
-
-    def accepts(self, workspace_id: Optional[str]) -> bool:
-        # Only the explicit no-auth/local ``None`` scope sees unscoped events.
-        # Any concrete set, including the authenticated fail-closed empty set,
-        # requires an exact workspace match.
-        if self.workspace_scope is None:
-            return True
-        return workspace_id in self.workspace_scope
-
-
-class RealtimeBus:
-    """In-process event bus with presence and a recent-activity ring buffer."""
-
-    def __init__(self) -> None:
-        self._subscribers: Dict[str, _Subscriber] = {}
-        self._feed: List[Dict[str, Any]] = []
-        self._presence: Dict[str, Dict[str, Any]] = {}
-        self._seq = 0
-        self._lock = threading.RLock()
-
-    # ── publishing ────────────────────────────────────────────────────────
-
-    def publish(self, event: Dict[str, Any]) -> Dict[str, Any]:
-        """Publish an event to matching subscribers + the activity feed.
-
-        Safe to call from sync code (e.g. the store's timeline hook). Never
-        raises and never blocks the caller.
-        """
-        with self._lock:
-            self._seq += 1
-            enriched = {
-                "seq": self._seq,
-                "received_at": _now(),
-                "area": event.get("area", "workspace"),
-                "event_type": event.get("event_type", "event"),
-                "workspace_id": event.get("workspace_id"),
-                "payload": event.get("payload", {}),
-                **{k: v for k, v in event.items() if k not in {"area", "event_type", "workspace_id", "payload"}},
-            }
-            enriched["contract"] = realtime_event_contract(enriched)
-            self._feed.append(enriched)
-            if len(self._feed) > _FEED_LIMIT:
-                self._feed = self._feed[-_FEED_LIMIT:]
-
-            workspace_id = enriched.get("workspace_id")
-            subscribers = [sub for sub in self._subscribers.values() if sub.accepts(workspace_id)]
-        for sub in subscribers:
-            if sub.loop is not None and sub.loop.is_running():
-                sub.loop.call_soon_threadsafe(self._enqueue, sub, enriched)
-            else:
-                self._enqueue(sub, enriched)
-        return enriched
-
-    @staticmethod
-    def _enqueue(sub: _Subscriber, event: Dict[str, Any]) -> None:
-        try:
-            sub.queue.put_nowait(event)
-        except asyncio.QueueFull:
-            try:
-                sub.queue.get_nowait()  # drop oldest
-                sub.queue.put_nowait(event)
-            except Exception:
-                quiet()
-
-    # The store calls ``event_sink(event)`` positionally; expose a stable alias.
-    def __call__(self, event: Dict[str, Any]) -> Dict[str, Any]:
-        return self.publish(event)
-
-    # ── subscription ──────────────────────────────────────────────────────
-
-    def add_subscriber(self, sub_id: str, *, workspace_scope: Optional[Set[str]] = None, user: Optional[str] = None) -> _Subscriber:
-        sub = _Subscriber(sub_id, workspace_scope, user)
-        with self._lock:
-            self._subscribers[sub_id] = sub
-        return sub
-
-    def remove_subscriber(self, sub_id: str) -> None:
-        with self._lock:
-            self._subscribers.pop(sub_id, None)
-
-    async def stream(
-        self,
-        sub: _Subscriber,
-        *,
-        heartbeat: float = 15.0,
-        refresh_authorization: Optional[Callable[[_Subscriber], bool]] = None,
-    ) -> AsyncIterator[str]:
-        """Yield SSE frames for a subscriber until the client disconnects.
-
-        Emits a periodic heartbeat comment so proxies keep the connection open
-        and single-user local mode never looks "stuck" with no events.
-        """
-        # Replay a small tail so a fresh subscriber has immediate context.
-        if refresh_authorization is not None and not refresh_authorization(sub):
-            self.remove_subscriber(sub.id)
-            return
-        for event in self.recent(limit=10, workspace_scope=sub.workspace_scope):
-            if refresh_authorization is not None and not refresh_authorization(sub):
-                self.remove_subscriber(sub.id)
-                return
-            if sub.accepts(event.get("workspace_id")):
-                yield sse_format(event)
-        try:
-            while True:
-                try:
-                    event = await asyncio.wait_for(sub.queue.get(), timeout=heartbeat)
-                    if refresh_authorization is not None and not refresh_authorization(sub):
-                        break
-                    # The event may have been queued under an older membership
-                    # snapshot. Recheck it against the refreshed scope before
-                    # any bytes leave the process.
-                    if sub.accepts(event.get("workspace_id")):
-                        yield sse_format(event)
-                except asyncio.TimeoutError:
-                    if refresh_authorization is not None and not refresh_authorization(sub):
-                        break
-                    yield ": heartbeat\n\n"
-        finally:
-            self.remove_subscriber(sub.id)
-
-    # ── feed + presence ─────────────────────────────────────────────────────
-
-    def recent(self, *, limit: int = 50, workspace_scope: Optional[Set[str]] = None) -> List[Dict[str, Any]]:
-        with self._lock:
-            events = list(self._feed)
-        if workspace_scope is not None:
-            events = [e for e in events if e.get("workspace_id") in workspace_scope]
-        return list(reversed(events[-max(1, min(limit, _FEED_LIMIT)):]))
-
-    def join(self, client_id: str, *, user: Optional[str], workspace_id: Optional[str]) -> Dict[str, Any]:
-        record = {
-            "client_id": client_id,
-            "user": user,
-            "workspace_id": workspace_id,
-            "joined_at": _now(),
-            "last_seen": _now(),
-        }
-        with self._lock:
-            existing = self._presence.get(client_id)
-            if existing is not None and existing.get("user") != user:
-                raise PermissionError("Presence client belongs to another user.")
-            self._presence[client_id] = record
-        self.publish({"area": "presence", "event_type": "join", "workspace_id": workspace_id, "payload": {"user": user, "client_id": client_id}})
-        return record
-
-    def heartbeat(self, client_id: str) -> Optional[Dict[str, Any]]:
-        with self._lock:
-            record = self._presence.get(client_id)
-            if record:
-                record["last_seen"] = _now()
-            return record
-
-    def leave(self, client_id: str, *, user: Optional[str] = None) -> None:
-        with self._lock:
-            record = self._presence.get(client_id)
-            if record is not None and user is not None and record.get("user") != user:
-                raise PermissionError("Presence client belongs to another user.")
-            record = self._presence.pop(client_id, None)
-        if record:
-            self.publish({"area": "presence", "event_type": "leave", "workspace_id": record.get("workspace_id"), "payload": {"client_id": client_id}})
-
-    def presence(self, *, workspace_scope: Optional[Set[str]] = None) -> List[Dict[str, Any]]:
-        with self._lock:
-            records = list(self._presence.values())
-        if workspace_scope is not None:
-            records = [r for r in records if r.get("workspace_id") in workspace_scope]
-        return records
-
-    def stats(self) -> Dict[str, Any]:
-        with self._lock:
-            return {
-                "version": REALTIME_VERSION,
-                "subscribers": len(self._subscribers),
-                "presence": len(self._presence),
-                "feed_size": len(self._feed),
-                "transport": "sse",
-            }

package/latticeai/core/run_explain.py

@@ -1,426 +0,0 @@
-"""Plain-language explanation of an agent run's outcome (v9.9.6).
-
-The loop already records *what* happened — :class:`~latticeai.core.agent_trace.LoopTrace`
-counters, the transcript, the terminal state. What it never produced was a
-sentence a person can read: why a run ended as ``NEEDS_REVIEW`` rather than
-``DONE``, or how much the model struggled with the tool-call format before it
-got there. Weak local models (Gemma-class) routinely need three format
-repairs and one correction hint to finish a task that a large model does in
-one pass; the counters showed that, the UI did not.
-
-This module turns the machine-readable signals into one honest, deterministic
-summary::
-
-    {"code": "no_evidence",
-     "headline": {"ko": "...", "en": "..."},
-     "details": [{"ko": "...", "en": "..."}],
-     "model_strain": {"level": "moderate", "parse_errors": 2, ...}}
-
-Rules the rest of the system relies on:
-
-* **Deterministic.** No model call, no clock, no I/O — the same run always
-  explains the same way, so tests and the eval harness can assert on it.
-* **Honest.** It never upgrades an outcome. A ``NEEDS_REVIEW`` explanation
-  says the result was not verified; it never reads as a soft success.
-* **Advisory.** Building an explanation must never fail a run — callers get a
-  minimal payload rather than an exception.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Dict, List, Mapping, Optional, Sequence
-
-from latticeai.core.messages import bilingual as _bilingual
-
-__all__ = ["explain_run", "STRAIN_LEVELS"]
-
-
-STRAIN_LEVELS = ("none", "light", "moderate", "heavy")
-
-# Repair names produced by ``extract_action_details`` / the artifact pipeline,
-# grouped so the explanation says what the model got wrong, not which internal
-# tolerance fired.
-_REPAIR_GROUPS: Dict[str, tuple] = {
-    "format": ("fence", "slice", "think_strip", "trailing_comma", "python_literal"),
-    "plan": (
-        "plan_not_object",
-        "goal_defaulted",
-        "steps_filtered",
-        "estimated_steps_invalid",
-        "manifest_steps",
-        "manifest_rewrite",
-        "heuristic_file_step",
-    ),
-    "artifact": ("artifact_sanitize", "artifact_repair"),
-}
-
-
-
-#: Historical module-local name for the shared phrase-pair helper.
-_phrase = _bilingual
-
-
-def _int(value: Any) -> int:
-    try:
-        return max(0, int(value))
-    except (TypeError, ValueError):
-        return 0
-
-
-def _steps(transcript: Any) -> List[Mapping[str, Any]]:
-    if not isinstance(transcript, Sequence) or isinstance(transcript, (str, bytes)):
-        return []
-    return [step for step in transcript if isinstance(step, Mapping)]
-
-
-def _last_verdict(steps: Sequence[Mapping[str, Any]]) -> Optional[Mapping[str, Any]]:
-    for step in reversed(steps):
-        if step.get("state") == "VERIFYING":
-            return step
-    return None
-
-
-def _repaired_artifacts(steps: Sequence[Mapping[str, Any]]) -> List[str]:
-    """Paths whose content the artifact pipeline had to repair into a scaffold."""
-    paths: List[str] = []
-    for step in steps:
-        meta = step.get("content_sanitize")
-        if not isinstance(meta, Mapping) or not meta.get("repaired"):
-            continue
-        raw_result = step.get("result")
-        raw_args = step.get("args")
-        result: Mapping[str, Any] = raw_result if isinstance(raw_result, Mapping) else {}
-        args: Mapping[str, Any] = raw_args if isinstance(raw_args, Mapping) else {}
-        path = result.get("path") or args.get("path")
-        if path and str(path) not in paths:
-            paths.append(str(path))
-    return paths
-
-
-def _blocked_actions(steps: Sequence[Mapping[str, Any]]) -> List[str]:
-    blocked: List[str] = []
-    for step in steps:
-        error = str(step.get("error") or "")
-        if error.startswith("BLOCKED:") and step.get("action"):
-            name = str(step["action"])
-            if name not in blocked:
-                blocked.append(name)
-    return blocked
-
-
-def _proposed_count(steps: Sequence[Mapping[str, Any]]) -> int:
-    return sum(
-        1
-        for step in steps
-        if isinstance(step.get("result"), Mapping) and step["result"].get("proposed")
-    )
-
-
-def _repair_totals(loop: Mapping[str, Any]) -> Dict[str, int]:
-    repairs = loop.get("repairs")
-    repairs = repairs if isinstance(repairs, Mapping) else {}
-    totals = {group: 0 for group in _REPAIR_GROUPS}
-    totals["other"] = 0
-    for name, count in repairs.items():
-        amount = _int(count)
-        for group, members in _REPAIR_GROUPS.items():
-            if name in members:
-                totals[group] += amount
-                break
-        else:
-            totals["other"] += amount
-    return totals
-
-
-def _strain_level(score: int) -> str:
-    if score <= 0:
-        return "none"
-    if score <= 2:
-        return "light"
-    if score <= 5:
-        return "moderate"
-    return "heavy"
-
-
-def _missing_files(steps: Sequence[Mapping[str, Any]]) -> List[str]:
-    """Requested files the run never wrote (from the coverage check)."""
-    for step in reversed(steps):
-        coverage = step.get("requirement_coverage")
-        if isinstance(coverage, Mapping):
-            missing = coverage.get("missing_files")
-            if isinstance(missing, Sequence) and not isinstance(missing, (str, bytes)):
-                return [str(path) for path in missing if path]
-    return []
-
-
-def _outcome(state: str, steps: Sequence[Mapping[str, Any]]) -> str:
-    """Terminal-state reason code — the *why*, not just the state name."""
-    verdict_step = _last_verdict(steps)
-    if state == "DONE":
-        return "done"
-    if state == "NEEDS_REVIEW":
-        if _missing_files(steps):
-            return "missing_files"
-        if verdict_step is None:
-            return "needs_review"
-        if verdict_step.get("verdict") == "UNAVAILABLE":
-            return "verifier_unavailable"
-        if verdict_step.get("verdict") == "PASS" and not verdict_step.get("evidence"):
-            return "no_evidence"
-        if verdict_step.get("next_state") == "DONE":
-            return "inconsistent_verdict"
-        return "needs_review"
-    if state == "FAILED":
-        if any(step.get("state") == "ROLLBACK" for step in steps):
-            return "rolled_back"
-        for step in steps:
-            if step.get("state") == "WAITING_APPROVAL" and (
-                step.get("decision") == "blocked_pending_approval"
-            ):
-                return "approval_required"
-        if verdict_step is not None and verdict_step.get("next_state") == "EXECUTING":
-            return "retry_budget"
-        return "failed"
-    return "unknown"
-
-
-_HEADLINES: Dict[str, Dict[str, str]] = {
-    "done": _phrase(
-        "요청한 작업을 끝냈고 검증도 통과했습니다.",
-        "The task finished and passed verification.",
-    ),
-    "verifier_unavailable": _phrase(
-        "작업은 실행됐지만 검증 모델의 답을 읽지 못해 '완료'로 처리하지 않았습니다.",
-        "The work ran, but the reviewing model's answer could not be read, so it was not marked complete.",
-    ),
-    "no_evidence": _phrase(
-        "검증자는 통과라고 했지만 실제로 실행된 기록이 없어 '완료'로 처리하지 않았습니다.",
-        "The reviewer said PASS but there is no record of anything actually running, so it was not marked complete.",
-    ),
-    "inconsistent_verdict": _phrase(
-        "검증 결과가 앞뒤가 맞지 않아 '완료'로 처리하지 않았습니다.",
-        "The verification verdict contradicted itself, so it was not marked complete.",
-    ),
-    "missing_files": _phrase(
-        "요청한 파일 중 일부가 만들어지지 않아 '완료'로 처리하지 않았습니다.",
-        "Some requested files were never written, so it was not marked complete.",
-    ),
-    "needs_review": _phrase(
-        "작업은 끝났지만 완료를 확인하지 못했습니다. 결과를 직접 확인해 주세요.",
-        "The run ended but completion could not be confirmed — please check the result yourself.",
-    ),
-    "rolled_back": _phrase(
-        "실행이 실패해서 바꾼 파일을 되돌렸습니다.",
-        "Execution failed, so the changed files were rolled back.",
-    ),
-    "approval_required": _phrase(
-        "승인이 필요한 도구가 있어 실행을 시작하지 못했습니다.",
-        "The run never started because it needed approval for a gated tool.",
-    ),
-    "retry_budget": _phrase(
-        "검증자가 계속 다시 하라고 해서 재시도 한도까지 갔고, 끝내 완료하지 못했습니다.",
-        "The reviewer kept asking for another attempt until the retry budget ran out.",
-    ),
-    "failed": _phrase(
-        "작업을 끝내지 못했습니다.",
-        "The task did not complete.",
-    ),
-    "unknown": _phrase(
-        "실행 상태를 확인하지 못했습니다.",
-        "The run state could not be determined.",
-    ),
-}
-
-
-_STRAIN_PHRASES: Dict[str, Dict[str, str]] = {
-    "light": _phrase(
-        "이 모델은 형식을 살짝 헷갈려 했지만 자동으로 정리했습니다.",
-        "The model slipped on the reply format once or twice; it was cleaned up automatically.",
-    ),
-    "moderate": _phrase(
-        "이 모델은 형식을 자주 틀려서 자동 보정이 여러 번 필요했습니다. 더 큰 모델을 쓰면 결과가 안정적입니다.",
-        "The model needed several automatic format repairs. A larger model would be steadier.",
-    ),
-    "heavy": _phrase(
-        "이 모델에게는 이 작업이 버거웠습니다 — 형식 오류와 보정이 많았습니다. 더 큰 모델로 다시 시도하는 것을 권합니다.",
-        "This task strained the model — many format errors and repairs. Consider retrying with a larger model.",
-    ),
-}
-
-
-def explain_run(
-    *,
-    state: Any,
-    loop: Optional[Mapping[str, Any]] = None,
-    transcript: Any = None,
-    max_retry: Optional[int] = None,
-) -> Dict[str, Any]:
-    """Explain one finished agent run in plain language.
-
-    ``state`` is the terminal :class:`~latticeai.core.agent.AgentState` value
-    (or its ``.value`` string), ``loop`` a :meth:`LoopTrace.summary` payload,
-    ``transcript`` the run transcript. Every argument is optional-tolerant:
-    a partial run still produces a usable payload rather than raising.
-    """
-    state_name = str(getattr(state, "value", state) or "").upper()
-    loop = loop if isinstance(loop, Mapping) else {}
-    steps = _steps(transcript)
-
-    code = _outcome(state_name, steps)
-    parse_errors = _int(loop.get("parse_errors"))
-    parse_recovered = _int(loop.get("parse_recovered"))
-    corrections = _int(loop.get("corrections"))
-    retries = _int(loop.get("retries"))
-    repair_totals = _repair_totals(loop)
-    repair_sum = sum(repair_totals.values())
-
-    strain_score = parse_errors * 2 + corrections + retries + repair_totals["format"]
-    strain: Dict[str, Any] = {
-        "level": _strain_level(strain_score),
-        "score": strain_score,
-        "parse_errors": parse_errors,
-        "parse_recovered": parse_recovered,
-        "corrections": corrections,
-        "retries": retries,
-        "repairs": repair_totals,
-        "repair_total": repair_sum,
-    }
-
-    details: List[Dict[str, str]] = []
-    if parse_errors:
-        details.append(_phrase(
-            f"모델이 정해진 형식을 {parse_errors}번 벗어났고, 그중 {parse_recovered}번은 자동으로 복구했습니다.",
-            f"The model broke the required reply format {parse_errors} time(s); "
-            f"{parse_recovered} of those were recovered automatically.",
-        ))
-    if repair_totals["format"]:
-        details.append(_phrase(
-            f"모델 응답을 {repair_totals['format']}번 자동으로 다듬어 읽었습니다 (코드블록·따옴표 정리 등).",
-            f"The model's reply needed {repair_totals['format']} automatic clean-up(s) "
-            "(code fences, quoting, stray text).",
-        ))
-    if repair_totals["plan"]:
-        details.append(_phrase(
-            f"계획이 비어 있거나 요청한 파일을 빠뜨려서 {repair_totals['plan']}번 자동으로 보완했습니다.",
-            f"The plan was empty or missed requested files and was repaired {repair_totals['plan']} time(s).",
-        ))
-    repaired_paths = _repaired_artifacts(steps)
-    if repaired_paths:
-        details.append(_phrase(
-            "다음 파일은 모델 출력이 온전하지 않아 기본 뼈대로 대신 저장했습니다 — 내용을 꼭 확인하세요: "
-            + ", ".join(repaired_paths[:4]),
-            "These files were saved as a generated scaffold because the model output was "
-            "not usable — check them: " + ", ".join(repaired_paths[:4]),
-        ))
-    if retries:
-        details.append(_phrase(
-            f"검증자가 {retries}번 다시 하라고 요청했습니다.",
-            f"The reviewer asked for another attempt {retries} time(s).",
-        ))
-    proposed = _proposed_count(steps)
-    if proposed:
-        details.append(_phrase(
-            f"기존 내용을 바꾸는 작업 {proposed}건은 바로 적용하지 않고 변경 제안으로 저장했습니다. 검토함에서 승인하면 적용됩니다.",
-            f"{proposed} change(s) to existing content were staged as review proposals "
-            "instead of applied — approve them in the review center.",
-        ))
-    blocked = _blocked_actions(steps)
-    if blocked:
-        details.append(_phrase(
-            "다음 도구는 정책상 막혀서 실행하지 않았습니다: " + ", ".join(blocked[:4]),
-            "These tools were blocked by policy and did not run: " + ", ".join(blocked[:4]),
-        ))
-    if code == "retry_budget" and max_retry:
-        details.append(_phrase(
-            f"재시도 한도({max_retry}회)에 도달했습니다.",
-            f"The retry budget ({max_retry}) was exhausted.",
-        ))
-    missing_files = _missing_files(steps)
-    if missing_files:
-        details.append(_phrase(
-            "만들어지지 않은 파일: " + ", ".join(missing_files[:4]),
-            "Files that were never written: " + ", ".join(missing_files[:4]),
-        ))
-    strain_phrase = _STRAIN_PHRASES.get(str(strain["level"]))
-    if strain_phrase is not None:
-        details.append(dict(strain_phrase))
-
-    return {
-        "code": code,
-        "state": state_name,
-        "ok": code == "done",
-        "headline": dict(_HEADLINES.get(code, _HEADLINES["unknown"])),
-        "details": details,
-        "model_strain": strain,
-        # Failure-learning surface (review 루프 §3): a structured "what to do
-        # differently", carried into the next plan by the project session
-        # instead of being lost with the run.
-        "next_step": _next_step(
-            code, missing_files=missing_files, blocked=blocked, strain=strain
-        ),
-    }
-
-
-_NEXT_STEPS: Dict[str, Dict[str, str]] = {
-    "verifier_unavailable": _phrase(
-        "검증 모델을 더 큰 모델로 바꾸거나, 결과를 직접 확인한 뒤 다시 실행하세요.",
-        "Switch the reviewing model to a larger one, or check the result yourself and re-run.",
-    ),
-    "no_evidence": _phrase(
-        "요청을 더 구체적으로 (무엇을 어디에 만들지) 적어 다시 실행하세요.",
-        "Re-run with a more concrete request — what to build and where.",
-    ),
-    "inconsistent_verdict": _phrase(
-        "결과를 확인한 뒤, 남은 부분만 다시 요청하세요.",
-        "Check the result, then re-request only what is still missing.",
-    ),
-    "approval_required": _phrase(
-        "승인 흐름으로 다시 실행하거나, 승인이 필요 없는 범위로 요청을 줄이세요.",
-        "Re-run through the approval flow, or narrow the request to steps that need no approval.",
-    ),
-    "rolled_back": _phrase(
-        "실패 원인을 확인한 뒤, 더 작은 단위로 나눠 다시 요청하세요.",
-        "Check what failed, then re-request in smaller steps.",
-    ),
-    "retry_budget": _phrase(
-        "요청을 더 작은 단계로 나누거나 더 큰 모델로 다시 시도하세요.",
-        "Split the request into smaller steps, or retry with a larger model.",
-    ),
-}
-
-
-def _next_step(
-    code: str,
-    *,
-    missing_files: Sequence[str],
-    blocked: Sequence[str],
-    strain: Mapping[str, Any],
-) -> Optional[Dict[str, str]]:
-    """One concrete "do this next", or None when the run needs nothing.
-
-    Specific evidence beats a generic template: a named missing file or a
-    blocked tool says more than "try again".
-    """
-    if code == "done" and str(strain.get("level")) in ("none", "light"):
-        return None
-    if missing_files:
-        names = ", ".join(list(missing_files)[:4])
-        return _phrase(
-            f"다음 파일만 다시 만들어 달라고 요청하세요: {names}",
-            f"Ask again for just these files: {names}",
-        )
-    if blocked:
-        names = ", ".join(list(blocked)[:3])
-        return _phrase(
-            f"막힌 도구({names}) 없이 할 수 있는 범위로 요청을 바꾸거나, 승인 후 다시 실행하세요.",
-            f"Rephrase the request to avoid the blocked tools ({names}), or approve them and re-run.",
-        )
-    specific = _NEXT_STEPS.get(code)
-    if specific is not None:
-        return dict(specific)
-    if str(strain.get("level")) == "heavy":
-        return _phrase(
-            "더 큰 모델로 다시 시도하면 성공률이 올라갑니다.",
-            "Retrying with a larger model will raise the success rate.",
-        )
-    return None