ltcai 11.5.2 → 11.7.0

package/latticeai/core/agent_prompts.py

@@ -1,171 +0,0 @@
-"""Role prompts for the Lattice multi-role agent runtime."""
-
-from __future__ import annotations
-
-from typing import Any, Optional
-
-from latticeai.core.tool_registry import TOOL_CATALOG_BRIEF
-
-PLANNER_PROMPT = """You are the PLANNER role in Lattice AI's multi-role agent harness.
-Your ONLY job: analyze the request and produce a structured execution plan.
-You do NOT call tools or write code.
-
-Respond with exactly ONE JSON object (no markdown, no fences):
-{
-  "action": "plan",
-  "state": "PLANNING",
-  "goal": "one-sentence goal in the user's language",
-  "steps": [
-    {"id": 1, "description": "what this step does", "action": "expected_tool", "purpose": "why needed"}
-  ],
-  "requires_approval": true,
-  "rollback_strategy": "git",
-  "estimated_steps": 3
-}
-
-Rules:
-- requires_approval = true if ANY step uses write/exec tools (edit_file, write_file, run_command, etc.)
-- rollback_strategy = "git" if steps modify existing files; "none" otherwise
-- Keep steps realistic: 2-4 for simple tasks, up to 10 for complex ones
-- Do NOT specify full tool args -- that is the Executor's job
-
-Available tools:""" + TOOL_CATALOG_BRIEF
-
-
-EXECUTOR_PROMPT = """You are the EXECUTOR role in Lattice AI's multi-role agent harness.
-You have a plan from the Planner. Execute it step by step using exactly one tool per response.
-
-You think and act like a senior software engineer:
-- Read (read_file, grep) BEFORE editing -- never guess at file contents
-- Prefer edit_file over write_file for existing files
-- Keep changes small and precise
-- Verify after changes with build_project or run_command
-
-Respond with exactly ONE JSON object per step:
-{"thoughts": "what you learned / why this next action", "action": "tool_name", "args": {...}}
-
-When writing a file (write_file), args.content must be the COMPLETE raw file
-content: no Markdown fences, no commentary, valid for the file's extension
-(an .html file starts with <!DOCTYPE html> and ends with </html>; a .json
-file must parse as strict JSON).
-
-When the task is fully done AND a tool result in this run confirms it:
-{"thoughts": "verified", "action": "final", "message": "한국어로 무엇을 했고 어디서 검증했는지 요약"}
-
-ANTI-PATTERNS (will halt the loop):
-- Editing without reading first -> read_file + grep BEFORE edit_file
-- Repeating the same action+args -> check the transcript
-- Claiming done without a verification tool result in transcript
-- Hallucinating imports or file paths that were never confirmed by a tool result
-
-Available tools:""" + TOOL_CATALOG_BRIEF
-
-
-CRITIC_PROMPT = """You are the CRITIC / REVIEWER role in Lattice AI's multi-role agent harness.
-Review the execution transcript and determine whether the goal was achieved.
-
-Respond with exactly ONE JSON object:
-{
-  "action": "verdict",
-  "state": "VERIFYING",
-  "verdict": "PASS",
-  "reason": "why you think it passed or failed (cite specific tool results)",
-  "corrections": [],
-  "confidence": 0.95,
-  "next_state": "DONE"
-}
-
-verdict: "PASS" | "FAIL"
-next_state:
-  "DONE"      -- task succeeded; finish
-  "EXECUTING" -- task failed but corrections can fix it (use corrections field for retry)
-  "ROLLBACK"  -- task failed AND file changes should be undone
-
-Criteria for PASS: a tool result in the transcript explicitly confirms success.
-Be strict. Claiming done without evidence = FAIL."""
-
-
-MEMORY_UPDATER_PROMPT = """You are the MEMORY UPDATER role in Lattice AI's multi-role agent harness.
-After a completed task, extract reusable learnings.
-
-Respond with exactly ONE JSON object:
-{
-  "action": "memory",
-  "state": "DONE",
-  "learnings": ["one concise fact about this codebase or task"],
-  "artifacts": ["relative/path/to/created_or_modified_file"],
-  "save_to_knowledge": false
-}
-
-Rules:
-- max 5 learnings, one sentence each
-- save_to_knowledge = true only if learnings are genuinely useful across future sessions
-- artifacts = files the Executor actually created or modified (from transcript)
-"""
-
-
-AGENT_SYSTEM_PROMPT = EXECUTOR_PROMPT
-
-
-# ── file-writing hints (v11.1.0) ────────────────────────────────────────────
-#
-# A 1–4B local model does not fail at *writing a file*; it fails at deciding
-# it is allowed to write one yet. The compact profile already gives that model
-# a shorter transcript and an earlier escalation; these hints give it the two
-# things the transcripts showed it missing most: a concrete order of
-# operations, and permission to write the file on the very next turn.
-#
-# The strings are deliberately additive — ``EXECUTOR_PROMPT`` is untouched, so
-# every caller that wants today's prompt keeps getting exactly today's prompt.
-
-FILE_TASK_HINTS = """
-FILE TASKS — how to actually finish one:
-- If the request names a file to create, your FIRST action is write_file with
-  the complete content. Do not read, list, or plan around it first.
-- args.path is a workspace-relative path (e.g. "report.md"), never absolute.
-- args.content is the WHOLE file, not a fragment and not a description of it.
-- After the write result appears in the transcript, verify once (read_file),
-  then finish with {"action": "final", ...}.
-"""
-
-COMPACT_FILE_TASK_HINTS = """
-FILE TASKS (short form):
-1. write_file {"path": "<name>", "content": "<the whole file>"}
-2. read_file to confirm it exists
-3. {"action": "final", "message": "..."}
-Write the file on your next turn. Do not explain first.
-"""
-
-
-def file_task_hints(profile: Any = None) -> str:
-    """The file-writing hints for a loop profile.
-
-    ``profile`` is an :class:`~latticeai.core.agent_profiles.AgentProfile`, its
-    name, or ``None``. The compact profile gets the numbered short form (small
-    models follow a list better than prose); everything else gets the standard
-    hints, so a strong model's prompt grows by four sentences and no rules.
-    """
-    name = getattr(profile, "name", profile)
-    if str(name or "").strip().lower() == "compact":
-        return COMPACT_FILE_TASK_HINTS.strip()
-    return FILE_TASK_HINTS.strip()
-
-
-def executor_prompt_for(
-    base: str = EXECUTOR_PROMPT,
-    *,
-    profile: Any = None,
-    self_model_summary: Optional[str] = None,
-) -> str:
-    """``base`` plus the file hints, and the Self-Model summary when there is one.
-
-    The injection rule is the same one the context builder follows: an empty
-    (or missing) Self-Model adds nothing at all — no header, no placeholder —
-    so a Brain that knows nothing about its owner produces the prompt it
-    always produced.
-    """
-    parts = [str(base or "").rstrip(), file_task_hints(profile)]
-    summary = str(self_model_summary or "").strip()
-    if summary:
-        parts.append(f"ABOUT THE USER (from their Brain — honour it, do not restate it):\n{summary}")
-    return "\n\n".join(parts)

package/latticeai/core/agent_registry.py

@@ -1,232 +0,0 @@
-"""Agent Registry — registration, discovery, metadata, versioning, capabilities.
-
-Part 2 of the v3.2.0 platform. Before this module the agent roster was derived
-ad-hoc from the hardcoded ``AGENT_ROLES`` tuple wherever it was needed. The
-registry makes every agent — built-in role and user-registered custom agent — a
-first-class entry with stable metadata: ``id``, ``type``, ``version``,
-``capabilities``, ``description`` and a mutable ``config``. The HTTP surface and
-the /app views read this registry instead of any hardcoded list.
-
-Built-in role agents are projected from the single source of truth in
-:mod:`lattice_brain.runtime.multi_agent` (so adding a role there flows through here).
-Custom agents and config overrides are persisted to
-``data_dir/agent_registry.json``.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import tempfile
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from lattice_brain.runtime.multi_agent import (
-    AGENT_ROLES,
-    CORE_PIPELINE,
-    MULTI_AGENT_VERSION,
-    ROLE_AGENT_IDS,
-)
-from latticeai.core.quiet import quiet
-
-from .timeutil import now_iso as _now
-
-AGENT_TYPES = ("planner", "researcher", "executor", "reviewer", "release", "custom")
-
-
-# Capabilities + descriptions for the built-in role agents. Kept here as the
-# registry's metadata projection of the roles defined in multi_agent.py.
-ROLE_META: Dict[str, Dict[str, Any]] = {
-    "researcher": {
-        "description": "Gathers workspace context, memory, and graph signal for the goal.",
-        "capabilities": ["context-retrieval", "memory-recall", "graph-read", "hybrid-search"],
-    },
-    "planner": {
-        "description": "Decomposes the goal into an ordered, bounded, reviewable plan.",
-        "capabilities": ["task-decomposition", "plan-review", "delegation"],
-    },
-    "executor": {
-        "description": "Executes each planned step, invoking tools, workflows, and plugins.",
-        "capabilities": ["tool-use", "workflow-run", "plugin-run", "file-write"],
-    },
-    "reviewer": {
-        "description": "Reviews executed work and approves, rejects, or requests a retry.",
-        "capabilities": ["verification", "retry-control", "approval"],
-    },
-    "release": {
-        "description": "Finalizes and summarizes the approved outcome.",
-        "capabilities": ["summarize", "finalize"],
-    },
-}
-
-
-class AgentRegistry:
-    """Persisted registry of built-in role agents + user-registered agents."""
-
-    def __init__(self, path: Path):
-        self.path = Path(path)
-        self._state: Dict[str, Any] = self._load()
-
-    # ── persistence ───────────────────────────────────────────────────────
-    def _load(self) -> Dict[str, Any]:
-        if self.path.exists():
-            try:
-                with open(self.path, "r", encoding="utf-8") as fh:
-                    data = json.load(fh)
-                if isinstance(data, dict):
-                    data.setdefault("custom", [])
-                    data.setdefault("config_overrides", {})
-                    return data
-            except Exception:
-                quiet()
-        return {"custom": [], "config_overrides": {}}
-
-    def _save(self) -> None:
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        fd, tmp = tempfile.mkstemp(dir=str(self.path.parent), suffix=".tmp")
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as fh:
-                json.dump(self._state, fh, ensure_ascii=False, indent=2)
-            os.replace(tmp, self.path)
-        finally:
-            if os.path.exists(tmp):
-                os.unlink(tmp)
-
-    # ── projection ────────────────────────────────────────────────────────
-    def _builtin_agents(self) -> List[Dict[str, Any]]:
-        overrides = self._state.get("config_overrides", {})
-        agents: List[Dict[str, Any]] = []
-        for role in AGENT_ROLES:
-            meta = ROLE_META.get(role, {"description": "", "capabilities": []})
-            agent_id = ROLE_AGENT_IDS.get(role, f"agent:{role}")
-            handoffs: List[str] = []
-            if role == "planner":
-                handoffs = [ROLE_AGENT_IDS["executor"]]
-            elif role == "executor":
-                handoffs = [ROLE_AGENT_IDS["reviewer"]]
-            ov = overrides.get(agent_id, {})
-            agents.append({
-                "id": agent_id,
-                "name": role.capitalize(),
-                "type": role,
-                "version": MULTI_AGENT_VERSION,
-                "description": meta["description"],
-                "capabilities": list(meta["capabilities"]),
-                "handoffs": handoffs,
-                "in_default_pipeline": role in CORE_PIPELINE,
-                "source": "builtin",
-                "removable": False,
-                "enabled": bool(ov.get("enabled", True)),
-                "config": ov.get("config", {}),
-            })
-        return agents
-
-    def _custom_agents(self) -> List[Dict[str, Any]]:
-        out: List[Dict[str, Any]] = []
-        for entry in self._state.get("custom", []):
-            agent = dict(entry)
-            agent["source"] = "user"
-            agent["removable"] = True
-            agent.setdefault("enabled", True)
-            agent.setdefault("handoffs", [])
-            out.append(agent)
-        return out
-
-    def all(self) -> List[Dict[str, Any]]:
-        return self._builtin_agents() + self._custom_agents()
-
-    # ── reads ─────────────────────────────────────────────────────────────
-    def list(self, agent_type: Optional[str] = None) -> Dict[str, Any]:
-        agents = self.all()
-        if agent_type:
-            agents = [a for a in agents if a["type"] == agent_type]
-        counts: Dict[str, int] = {}
-        for a in self.all():
-            counts[a["type"]] = counts.get(a["type"], 0) + 1
-        return {
-            "agents": agents,
-            "types": list(AGENT_TYPES),
-            "counts": counts,
-            "total": len(agents),
-            "version": MULTI_AGENT_VERSION,
-            "default_pipeline": list(CORE_PIPELINE),
-            "generated_at": _now(),
-        }
-
-    def get(self, agent_id: str) -> Optional[Dict[str, Any]]:
-        return next((a for a in self.all() if a["id"] == agent_id), None)
-
-    def capabilities(self) -> Dict[str, List[str]]:
-        """Inverted index: capability -> [agent_id, …]."""
-        index: Dict[str, List[str]] = {}
-        for a in self.all():
-            for cap in a.get("capabilities", []):
-                index.setdefault(cap, []).append(a["id"])
-        return index
-
-    def discover(self, capability: str) -> List[Dict[str, Any]]:
-        cap = str(capability or "").lower().strip()
-        return [a for a in self.all() if any(cap == c.lower() for c in a.get("capabilities", []))]
-
-    # ── mutations ─────────────────────────────────────────────────────────
-    def register(
-        self,
-        *,
-        name: str,
-        agent_type: str = "custom",
-        description: str = "",
-        capabilities: Optional[List[str]] = None,
-        config: Optional[Dict[str, Any]] = None,
-        version: str = "1.0.0",
-    ) -> Dict[str, Any]:
-        if not str(name).strip():
-            raise ValueError("name is required")
-        if agent_type not in AGENT_TYPES:
-            raise ValueError(f"type must be one of {', '.join(AGENT_TYPES)}")
-        slug = str(name).strip().lower().replace(" ", "-")
-        agent_id = f"agent:custom:{slug}"
-        existing = {c["id"] for c in self._state.get("custom", [])}
-        if agent_id in existing:
-            agent_id = f"agent:custom:{slug}-{len(existing) + 1}"
-        entry = {
-            "id": agent_id,
-            "name": str(name).strip(),
-            "type": agent_type,
-            "version": str(version or "1.0.0"),
-            "description": str(description or "").strip(),
-            "capabilities": list(capabilities or []),
-            "config": dict(config or {}),
-            "enabled": True,
-            "created_at": _now(),
-        }
-        self._state.setdefault("custom", []).append(entry)
-        self._save()
-        return entry
-
-    def update_config(self, agent_id: str, config: Dict[str, Any], *, enabled: Optional[bool] = None) -> Dict[str, Any]:
-        if self.get(agent_id) is None:
-            raise KeyError(agent_id)
-        if agent_id.startswith("agent:custom:"):
-            for entry in self._state.get("custom", []):
-                if entry["id"] == agent_id:
-                    entry["config"] = dict(config or {})
-                    if enabled is not None:
-                        entry["enabled"] = bool(enabled)
-                    entry["updated_at"] = _now()
-        else:
-            ov = self._state.setdefault("config_overrides", {}).setdefault(agent_id, {})
-            ov["config"] = dict(config or {})
-            if enabled is not None:
-                ov["enabled"] = bool(enabled)
-        self._save()
-        return self.get(agent_id)  # type: ignore[return-value]
-
-    def remove(self, agent_id: str) -> Dict[str, Any]:
-        if not agent_id.startswith("agent:custom:"):
-            raise ValueError("Built-in role agents cannot be removed; disable them via config instead.")
-        before = len(self._state.get("custom", []))
-        self._state["custom"] = [c for c in self._state.get("custom", []) if c["id"] != agent_id]
-        if len(self._state["custom"]) == before:
-            raise KeyError(agent_id)
-        self._save()
-        return {"removed": agent_id}

package/latticeai/core/agent_state.py

@@ -1,41 +0,0 @@
-"""The agent loop's state vocabulary.
-
-Its own module because both sides of the runtime need it and neither can own
-it: :mod:`latticeai.core.agent` holds the state machine, and
-:mod:`latticeai.core.agent_helpers` holds the pure functions the machine calls.
-If the enum lived in ``agent``, the helpers would have to import the module
-that imports them — so they would fall back to writing ``"EXECUTING"`` as a
-bare string, and a rename of the enum value would silently stop matching.
-
-Both names stay importable from :mod:`latticeai.core.agent`, which is where
-every existing caller expects them.
-"""
-
-from __future__ import annotations
-
-from enum import Enum
-from typing import FrozenSet
-
-
-class AgentState(str, Enum):
-    IDLE             = "IDLE"
-    PLANNING         = "PLANNING"
-    WAITING_APPROVAL = "WAITING_APPROVAL"
-    EXECUTING        = "EXECUTING"
-    VERIFYING        = "VERIFYING"
-    FAILED           = "FAILED"
-    ROLLBACK         = "ROLLBACK"
-    # Terminal, non-success: the run ended but completion could not be
-    # verified (critic unavailable/unparseable, or a PASS with no execution
-    # evidence). Never presented as success — the user must check the result.
-    NEEDS_REVIEW     = "NEEDS_REVIEW"
-    DONE             = "DONE"
-
-
-# Terminal states — the agent loop exits when reaching one of these
-AGENT_TERMINAL_STATES: FrozenSet[AgentState] = frozenset(
-    {AgentState.DONE, AgentState.FAILED, AgentState.NEEDS_REVIEW}
-)
-
-
-__all__ = ["AgentState", "AGENT_TERMINAL_STATES"]

package/latticeai/core/agent_trace.py

@@ -1,104 +0,0 @@
-"""Structured observability for the single-agent reasoning loop (v9.6.0).
-
-The PLAN → EXECUTE → VERIFY state machine in :mod:`latticeai.core.agent`
-already keeps a human-readable transcript, but the transcript mixes model
-output, tool results, and control decisions into one list — you cannot ask
-"how many parse failures were recovered?" or "which repairs did the weak
-model need?" without re-parsing it.
-
-:class:`LoopTrace` is the machine-readable side channel: every phase records
-typed events (llm_call, parse_error, repair, correction, tool call outcome,
-blocked action, retry, rollback), and :meth:`LoopTrace.summary` reduces them
-to the counters an evaluation harness or the API response can consume
-directly. The trace is pure data — no I/O, no clock dependency beyond an
-injectable timestamp function — so unit tests and the deterministic agent
-evaluation harness can assert on it exactly.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Callable, Dict, List, Optional
-
-from latticeai.core.timeutil import now_iso
-
-_MAX_EVENTS = 500
-
-
-class LoopTrace:
-    """Typed event stream + summary counters for one agent run."""
-
-    def __init__(self, clock: Optional[Callable[[], str]] = None) -> None:
-        self._clock = clock or now_iso
-        self.events: List[Dict[str, Any]] = []
-        self.truncated = 0
-
-    def record(self, phase: str, kind: str, **details: Any) -> None:
-        if len(self.events) >= _MAX_EVENTS:
-            self.truncated += 1
-            return
-        event: Dict[str, Any] = {"phase": phase, "kind": kind, "at": self._clock()}
-        for key, value in details.items():
-            if value is not None:
-                event[key] = value
-        self.events.append(event)
-
-    # ── typed helpers keep call sites terse and the vocabulary closed ────
-
-    def llm_call(self, phase: str, *, model: Optional[str] = None) -> None:
-        self.record(phase, "llm_call", model=model)
-
-    def parse_error(self, phase: str, *, error: str, recovered: bool) -> None:
-        self.record(phase, "parse_error", error=error[:200], recovered=recovered)
-
-    def repair(self, phase: str, *, repairs: List[str]) -> None:
-        if repairs:
-            self.record(phase, "repair", repairs=list(repairs))
-
-    def correction(self, phase: str, *, hint: str) -> None:
-        self.record(phase, "correction", hint=hint[:200])
-
-    def tool(self, phase: str, *, name: str, outcome: str, risk: Optional[str] = None) -> None:
-        self.record(phase, "tool", name=name, outcome=outcome, risk=risk)
-
-    def decision(self, phase: str, *, decision: str, **details: Any) -> None:
-        self.record(phase, "decision", decision=decision, **details)
-
-    def retry(self, phase: str, *, attempt: int) -> None:
-        self.record(phase, "retry", attempt=attempt)
-
-    # ── reduction ────────────────────────────────────────────────────────
-
-    def summary(self) -> Dict[str, Any]:
-        counts: Dict[str, int] = {}
-        tool_outcomes: Dict[str, int] = {}
-        repairs: Dict[str, int] = {}
-        parse_errors = 0
-        parse_recovered = 0
-        for event in self.events:
-            kind = event["kind"]
-            counts[kind] = counts.get(kind, 0) + 1
-            if kind == "tool":
-                outcome = str(event.get("outcome") or "unknown")
-                tool_outcomes[outcome] = tool_outcomes.get(outcome, 0) + 1
-            elif kind == "parse_error":
-                parse_errors += 1
-                if event.get("recovered"):
-                    parse_recovered += 1
-            elif kind == "repair":
-                for name in event.get("repairs") or []:
-                    repairs[name] = repairs.get(name, 0) + 1
-        return {
-            "events": len(self.events),
-            "truncated_events": self.truncated,
-            "kind_counts": counts,
-            "llm_calls": counts.get("llm_call", 0),
-            "parse_errors": parse_errors,
-            "parse_recovered": parse_recovered,
-            "corrections": counts.get("correction", 0),
-            "retries": counts.get("retry", 0),
-            "tool_outcomes": tool_outcomes,
-            "repairs": repairs,
-        }
-
-
-__all__ = ["LoopTrace"]

package/latticeai/core/artifact_ledger.py

@@ -1,109 +0,0 @@
-"""Conversation artifact ledger — closing the re-search loop (v9.9.6).
-
-A run writes ``index.html``, the file is queued for ingestion, and the user
-immediately asks "이제 그 파일에 다크모드 넣어줘". Indexing (chunking, embedding,
-graph writes) is asynchronous, so retrieval may not know about that file yet —
-the next turn could plan as if it had never been created.
-
-This ledger is the deterministic bridge: the agent path records what it just
-wrote, and the context assembler injects it as a high-priority section. It is
-intentionally **process-local and bounded**:
-
-* it answers "what did *this conversation* just make?", a question whose
-  useful lifetime is minutes;
-* by the time a restart loses it, the ingestion pipeline has indexed those
-  files and normal retrieval answers better than a ledger would;
-* nothing downstream may treat it as durable storage — the Brain remains the
-  single durable home for knowledge.
-"""
-
-from __future__ import annotations
-
-import threading
-from collections import OrderedDict
-from typing import Any, Dict, List, Optional, Sequence
-
-from latticeai.core.timeutil import now_iso
-
-__all__ = ["ArtifactLedger"]
-
-
-class ArtifactLedger:
-    """Bounded, thread-safe map of conversation → recently written artifacts."""
-
-    def __init__(
-        self,
-        *,
-        max_conversations: int = 200,
-        max_per_conversation: int = 25,
-    ) -> None:
-        self._lock = threading.Lock()
-        self._entries: "OrderedDict[tuple, List[Dict[str, Any]]]" = OrderedDict()
-        self._max_conversations = max(1, int(max_conversations))
-        self._max_per_conversation = max(1, int(max_per_conversation))
-
-    @staticmethod
-    def _key(
-        user_email: Optional[str],
-        conversation_id: Optional[str],
-        workspace_id: Optional[str],
-    ) -> tuple:
-        return (
-            str(user_email or ""),
-            str(conversation_id or "default"),
-            str(workspace_id or ""),
-        )
-
-    def record(
-        self,
-        paths: Sequence[Any],
-        *,
-        user_email: Optional[str] = None,
-        conversation_id: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        run_id: str = "",
-    ) -> List[Dict[str, Any]]:
-        """Note artifacts this conversation just produced. Never raises."""
-        cleaned: List[str] = []
-        for entry in list(paths or []):
-            path = entry if isinstance(entry, str) else (entry or {}).get("path")
-            path = str(path or "").strip()
-            if path and path not in cleaned:
-                cleaned.append(path)
-        if not cleaned:
-            return []
-        stamp = now_iso()
-        key = self._key(user_email, conversation_id, workspace_id)
-        with self._lock:
-            existing = self._entries.pop(key, [])
-            by_path = {item["path"]: item for item in existing}
-            for path in cleaned:
-                by_path[path] = {"path": path, "at": stamp, "run_id": str(run_id or "")}
-            merged = sorted(by_path.values(), key=lambda item: item["at"])
-            merged = merged[-self._max_per_conversation :]
-            self._entries[key] = merged
-            while len(self._entries) > self._max_conversations:
-                self._entries.popitem(last=False)
-            return list(merged)
-
-    def recent(
-        self,
-        *,
-        user_email: Optional[str] = None,
-        conversation_id: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        limit: int = 10,
-    ) -> List[Dict[str, Any]]:
-        """Most recent artifacts for one conversation, newest last.
-
-        Returns ``[]`` for an unknown conversation — honest absence, never a
-        cross-conversation leak.
-        """
-        key = self._key(user_email, conversation_id, workspace_id)
-        with self._lock:
-            items = list(self._entries.get(key, []))
-        return items[-max(1, int(limit)) :]
-
-    def clear(self) -> None:
-        with self._lock:
-            self._entries.clear()