devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/live/cards.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 import hashlib
 import json
+import re
+from dataclasses import dataclass
 from pathlib import Path
 
-from devcouncil.live.models import AgentTurn, CardStatus, CritiqueCard
+from devcouncil.live.models import AgentTurn, CardStatus, CritiqueCard, Verdict
 
 RISK_TERMS = (
     "skip tests",
@@ -31,21 +33,171 @@ EVIDENCE_TERMS = (
     "verified",
 )
 
+# Word-boundary matchers so "done" matches "I'm done" but not "abandoned"/"undone".
+_COMPLETION_RE = re.compile(
+    r"\b(done|complete|completed|finished|implemented|fixed|ready|all set|"
+    r"ship it|good to go|works now|it works)\b"
+)
+# An agent asserting its verification actually passed (the claim we cross-check).
+_PASS_CLAIM_RE = re.compile(
+    r"(tests?\s+(?:are\s+|now\s+)?pass(?:ing|ed|es)?"
+    r"|all\s+(?:tests?|checks?|cases?)\s+pass"
+    r"|passing\s+tests?"
+    r"|\bverified\b|verification\s+(?:pass|succeed)"
+    r"|tests?\s+green|green\s+tests?"
+    r"|(?:ran|run)\s+[^.\n]{0,40}?\bpass)"
+)
+# Negations that flip a nearby claim ("not done", "tests do not pass", "still failing").
+_NEGATION_RE = re.compile(
+    r"\b(not|isn'?t|aren'?t|won'?t|can'?t|cannot|haven'?t|hasn'?t|don'?t|"
+    r"doesn'?t|didn'?t|no longer|never|yet to|still need|still failing|"
+    r"not yet|unable|fail(?:s|ing|ed)?)\b"
+)
+_NEGATION_WINDOW = 30
+
+
+def _claim_present(pattern: re.Pattern[str], lower: str) -> bool:
+    """True if `pattern` matches and is not negated by a word shortly before it."""
+    for match in pattern.finditer(lower):
+        prefix = lower[max(0, match.start() - _NEGATION_WINDOW):match.start()]
+        if _NEGATION_RE.search(prefix):
+            continue
+        return True
+    return False
+
+
+@dataclass
+class _TaskGrounding:
+    """A snapshot of a task's real verification state from the artifact graph."""
+
+    task_id: str
+    status: str
+    blocking_gaps: int
+    failing_commands: int
+    acs_total: int
+    acs_passing: int
+
+    @property
+    def acs_unproven(self) -> int:
+        return max(0, self.acs_total - self.acs_passing)
+
+    @property
+    def is_satisfied(self) -> bool:
+        return (
+            self.status in ("verified", "done")
+            and self.blocking_gaps == 0
+            and (self.acs_total == 0 or self.acs_passing >= self.acs_total)
+        )
+
+
+def _load_task_grounding(project_root: Path, task_id: str | None) -> _TaskGrounding | None:
+    """Load the scoped task's real verification state so claims can be checked
+    against evidence instead of trusted on the agent's word. Best-effort: any
+    failure (no DB, unknown task) returns None and the caller falls back to the
+    pure-heuristic review."""
+    if not task_id:
+        return None
+    try:
+        from devcouncil.storage.db import get_db
+        from devcouncil.storage.repositories import ArtifactGraphRepository
+
+        db = get_db(project_root)
+        if not db:
+            return None
+        with db.get_session() as session:
+            graph = ArtifactGraphRepository(session).load_graph()
+    except Exception:
+        return None
+
+    task = graph.tasks.get(task_id)
+    if task is None:
+        return None
+
+    blocking = [g for g in graph.gaps.values() if g.task_id == task_id and g.blocking]
+    failing = [g for g in blocking if g.gap_type == "test_failed"]
+    ac_ids = set(task.acceptance_criterion_ids)
+    passing_ac = {
+        ev.acceptance_criterion_id
+        for ev in graph.test_evidence
+        if ev.acceptance_criterion_id in ac_ids and getattr(ev, "status", "") == "passed"
+    }
+    return _TaskGrounding(
+        task_id=task_id,
+        status=task.status,
+        blocking_gaps=len(blocking),
+        failing_commands=len(failing),
+        acs_total=len(ac_ids),
+        acs_passing=len(passing_ac),
+    )
+
 
-def review_turn(turn: AgentTurn, project_root: Path, client: str | None = None) -> CritiqueCard:
-    """Generate a deterministic critique card for an agent response."""
+def review_turn(
+    turn: AgentTurn,
+    project_root: Path,
+    client: str | None = None,
+    task_id: str | None = None,
+) -> CritiqueCard:
+    """Generate a deterministic critique card for an agent response.
+
+    When ``task_id`` resolves to a known task, completion/verification claims are
+    checked against the task's real artifact state (status, blocking gaps, passing
+    acceptance-criterion evidence) instead of being trusted by keyword alone. With
+    no task state available it falls back to the lightweight keyword heuristic.
+    """
     content = turn.content.strip()
     lower = content.lower()
     concerns: list[str] = []
     alternatives: list[str] = []
     evidence_requests: list[str] = []
+    verdict: Verdict = "Approved"
+
+    grounding = _load_task_grounding(project_root, task_id)
 
     risky_terms = [term for term in RISK_TERMS if term in lower]
     if risky_terms:
         concerns.append(f"Response contains risky implementation language: {', '.join(risky_terms[:4])}.")
         alternatives.append("Replace risky shortcuts with a scoped implementation and explicit rollback or verification path.")
 
-    if _looks_like_completion_claim(lower) and not any(term in lower for term in EVIDENCE_TERMS):
+    claims_completion = _claim_present(_COMPLETION_RE, lower)
+    claims_passing = _claim_present(_PASS_CLAIM_RE, lower)
+
+    if grounding is not None:
+        # Evidence-grounded review: cross-check the agent's claims against reality.
+        if claims_passing and grounding.failing_commands > 0:
+            concerns.append(
+                f"Agent claims verification passes, but DevCouncil recorded "
+                f"{grounding.failing_commands} failing verification command(s) for "
+                f"task {grounding.task_id}."
+            )
+            evidence_requests.append(
+                f"Re-run 'dev verify {grounding.task_id}' and fix the failing command(s) "
+                "before claiming success."
+            )
+            verdict = "Critical Issues"
+        elif (claims_completion or claims_passing) and not grounding.is_satisfied:
+            details = [f"task {grounding.task_id} is '{grounding.status}'"]
+            if grounding.blocking_gaps:
+                details.append(f"{grounding.blocking_gaps} blocking gap(s)")
+            if grounding.acs_unproven:
+                details.append(
+                    f"{grounding.acs_unproven}/{grounding.acs_total} acceptance "
+                    "criteria still lack passing evidence"
+                )
+            concerns.append(
+                "Completion claim is not yet backed by DevCouncil evidence: "
+                + ", ".join(details) + "."
+            )
+            evidence_requests.append(
+                f"Run 'dev verify {grounding.task_id}' and resolve the gaps so the "
+                "claim is supported by passing evidence."
+            )
+        elif claims_completion and grounding.is_satisfied:
+            alternatives.append(
+                f"Completion is corroborated by passing evidence for task {grounding.task_id}; "
+                "proceed."
+            )
+    elif claims_completion and not any(term in lower for term in EVIDENCE_TERMS):
+        # No task state to ground against: best-effort keyword heuristic.
         concerns.append("The response appears to claim completion without naming verification evidence.")
         evidence_requests.append("State the exact commands, checks, or reviewed artifacts that prove the change.")
 
@@ -56,8 +208,7 @@ def review_turn(turn: AgentTurn, project_root: Path, client: str | None = None)
     if "todo" in lower or "follow-up" in lower or "later" in lower:
         evidence_requests.append("List any remaining TODOs as DevCouncil gaps or repair tasks instead of burying them in chat.")
 
-    verdict = "Approved"
-    if concerns:
+    if concerns and verdict == "Approved":
         verdict = "Concerns"
     if any(term in lower for term in ("--no-verify", "reset --hard", "force push", "ignore failing")):
         verdict = "Critical Issues"
@@ -69,9 +220,11 @@ def review_turn(turn: AgentTurn, project_root: Path, client: str | None = None)
     message_for_agent = _message_for_agent(verdict, concerns, evidence_requests)
     card_id = _card_id(turn)
     return CritiqueCard(
+        schema="devcouncil.critique_card.v1",
         id=card_id,
         session_id=turn.session_id,
         turn_id=turn.turn_id,
+        task_id=task_id,
         client=client or turn.source,
         verdict=verdict,
         summary=summary,
@@ -146,11 +299,19 @@ def filter_cards(
     return filtered, None, None
 
 
+def load_card_by_id(project_root: Path, card_id: str) -> CritiqueCard | None:
+    """Read a single card directly by id, avoiding a scan of every card file."""
+    path = card_path(project_root, card_id)
+    if not path.exists():
+        return None
+    try:
+        return CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8")))
+    except Exception:
+        return None
+
+
 def get_card(project_root: Path, card_id: str) -> CritiqueCard | None:
-    for card in load_cards(project_root):
-        if card.id == card_id:
-            return card
-    return None
+    return load_card_by_id(project_root, card_id)
 
 
 def update_card_status(project_root: Path, card_id: str, status: CardStatus) -> CritiqueCard | None:
@@ -164,30 +325,25 @@ def update_card_status(project_root: Path, card_id: str, status: CardStatus) ->
     return updated
 
 
-def unresolved_blocking_cards(project_root: Path, task_id: str | None = None) -> list[CritiqueCard]:
+def unresolved_blocking_cards(
+    project_root: Path,
+    task_id: str | None = None,
+    *,
+    cards: list[CritiqueCard] | None = None,
+) -> list[CritiqueCard]:
+    source = cards if cards is not None else load_cards(project_root)
     return [
-        card for card in load_cards(project_root)
+        card for card in source
         if card.status == "open" and card.verdict == "Critical Issues"
         and (task_id is None or card.task_id in {None, task_id})
     ]
 
 
 def _card_id(turn: AgentTurn) -> str:
-    digest = hashlib.sha1(f"{turn.session_id}:{turn.turn_id}:{turn.content}".encode("utf-8")).hexdigest()
+    digest = hashlib.sha256(f"{turn.session_id}:{turn.turn_id}:{turn.content}".encode("utf-8")).hexdigest()
     return f"CARD-{digest[:12]}"
 
 
-def _looks_like_completion_claim(lower: str) -> bool:
-    return any(phrase in lower for phrase in (
-        "done",
-        "completed",
-        "implemented",
-        "fixed",
-        "ready",
-        "all set",
-    ))
-
-
 def _mentions_broad_change(lower: str) -> bool:
     return any(phrase in lower for phrase in (
         "refactor the entire",
@@ -198,7 +354,7 @@ def _mentions_broad_change(lower: str) -> bool:
     ))
 
 
-def _message_for_agent(verdict: str, concerns: list[str], evidence_requests: list[str]) -> str:
+def _message_for_agent(verdict: Verdict, concerns: list[str], evidence_requests: list[str]) -> str:
     if verdict == "Approved":
         return "Continue, but keep the next response grounded in changed files and verification evidence."
     pieces = ["Pause and address this review before proceeding."]

package/src/devcouncil/live/repair_prompt.py

@@ -8,8 +8,16 @@ from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import RequirementRepository, TaskRepository
 
 
-def build_live_repair_prompt(project_root: Path, card: CritiqueCard) -> str:
-    """Build a ready-to-paste repair prompt for a live-review critique card."""
+def build_live_repair_prompt(
+    project_root: Path,
+    card: CritiqueCard,
+    requirements: list | None = None,
+) -> str:
+    """Build a ready-to-paste repair prompt for a live-review critique card.
+
+    ``requirements`` may be pre-fetched (e.g. by the bulk builder) to avoid
+    re-querying every requirement once per card. ``None`` fetches them as before.
+    """
     prompt = [
         f"# Repair Live Review Card {card.id}",
         "",
@@ -34,7 +42,7 @@ def build_live_repair_prompt(project_root: Path, card: CritiqueCard) -> str:
     if card.message_for_agent:
         prompt.extend(["", "## Message For Agent", card.message_for_agent])
 
-    task_prompt = _task_prompt(project_root, card.task_id)
+    task_prompt = _task_prompt(project_root, card.task_id, requirements=requirements)
     if task_prompt:
         prompt.extend(["", "## Original DevCouncil Task Contract", task_prompt])
 
@@ -59,17 +67,31 @@ def build_bulk_live_repair_prompt(project_root: Path, cards: list[CritiqueCard])
         "",
         f"DevCouncil found {len(cards)} blocking live-review card(s). Address each card below.",
     ]
+    requirements = _load_all_requirements(project_root)
     for index, card in enumerate(cards, start=1):
         sections.extend([
             "",
             f"---\n\n## Card {index}: {card.id}",
             "",
-            build_live_repair_prompt(project_root, card).strip(),
+            build_live_repair_prompt(project_root, card, requirements=requirements).strip(),
         ])
     return "\n".join(sections).rstrip() + "\n"
 
 
-def _task_prompt(project_root: Path, task_id: str | None) -> str | None:
+def _load_all_requirements(project_root: Path) -> list | None:
+    """Fetch all requirements once; returns None when no DB is available."""
+    db = get_db(project_root)
+    if not db:
+        return None
+    with db.get_session() as session:
+        return RequirementRepository(session).get_all()
+
+
+def _task_prompt(
+    project_root: Path,
+    task_id: str | None,
+    requirements: list | None = None,
+) -> str | None:
     if not task_id:
         return None
     db = get_db(project_root)
@@ -79,5 +101,6 @@ def _task_prompt(project_root: Path, task_id: str | None) -> str | None:
         task = TaskRepository(session).get_by_id(task_id)
         if not task:
             return None
-        requirements = RequirementRepository(session).get_all()
+        if requirements is None:
+            requirements = RequirementRepository(session).get_all()
     return PromptBuilder(project_root).build_task_prompt(task, requirements)

package/src/devcouncil/live/reviewer.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 
 from devcouncil.live.cards import review_turn
 from devcouncil.live.models import AgentTurn, CritiqueCard
 from devcouncil.llm.router import ModelRouter
 
+logger = logging.getLogger(__name__)
+
 
 class LiveReviewService:
     """Reviews coding-agent responses with deterministic or model-backed critique cards."""
@@ -23,6 +26,7 @@ class LiveReviewService:
     ) -> CritiqueCard:
         fallback = review_turn(turn, project_root, client=client)
         if not use_llm or self.router is None:
+            logger.debug("Live review (deterministic) for %s turn=%s: %s", client, turn.turn_id, fallback.verdict)
             return fallback
 
         prompt = f"""
@@ -46,21 +50,41 @@ Turn: {turn.turn_id}
 Assistant response:
 {turn.content}
 """
-        try:
-            reviewed = await self.router.complete_structured(
-                role=self.role,
-                messages=[{"role": "user", "content": prompt}],
-                schema=CritiqueCard,
-            )
-        except ValueError:
-            reviewed = await self.router.complete_structured(
-                role="implementation_reviewer",
-                messages=[{"role": "user", "content": prompt}],
-                schema=CritiqueCard,
-            )
-        except Exception:
+        samples = self._samples(project_root)
+        cards: list[CritiqueCard] = []
+        for attempt in range(samples):
+            # Vary temperature so independent samples actually differ (and so the router
+            # cache returns distinct generations). Attempt 0 stays deterministic.
+            temperature = 0.0 if attempt == 0 else min(0.8, 0.3 + 0.2 * attempt)
+            try:
+                cards.append(await self.router.complete_structured(
+                    role=self.role,
+                    messages=[{"role": "user", "content": prompt}],
+                    schema=CritiqueCard,
+                    temperature=temperature,
+                ))
+            except ValueError:
+                try:
+                    cards.append(await self.router.complete_structured(
+                        role="implementation_reviewer",
+                        messages=[{"role": "user", "content": prompt}],
+                        schema=CritiqueCard,
+                        temperature=temperature,
+                    ))
+                except Exception:
+                    continue
+            except Exception:
+                continue
+
+        if not cards:
+            logger.warning("Live review produced no cards for %s turn=%s; using deterministic fallback", client, turn.turn_id)
             return fallback
 
+        reviewed = self._vote(cards)
+        logger.info(
+            "Live review (LLM, %d sample(s)) for %s turn=%s: %s",
+            len(cards), client, turn.turn_id, reviewed.verdict,
+        )
         return reviewed.model_copy(update={
             "id": fallback.id,
             "session_id": turn.session_id,
@@ -68,3 +92,38 @@ Assistant response:
             "client": client,
             "source_path": fallback.source_path,
         })
+
+    def _samples(self, project_root: Path) -> int:
+        try:
+            from devcouncil.app.config import load_config
+            return max(1, load_config(project_root).verification.reviewer_checks.samples)
+        except Exception:
+            return 1
+
+    @staticmethod
+    def _vote(cards: list[CritiqueCard]) -> CritiqueCard:
+        """Majority-vote the verdict across independent reviews, then return a card whose
+        verdict matches the vote (so its concerns/evidence are consistent).
+
+        A single review is returned as-is. With several, the BLOCKING verdict
+        ("Critical Issues") is chosen only on a strict majority, and "Approved" likewise;
+        anything else de-escalates to the non-blocking "Concerns". This prevents a lone
+        mis-calibrated reviewer from blocking, without ever auto-approving a real concern."""
+        if len(cards) == 1:
+            return cards[0]
+        from collections import Counter
+
+        counts = Counter(card.verdict for card in cards)
+        threshold = len(cards) / 2
+        if counts.get("Critical Issues", 0) > threshold:
+            verdict = "Critical Issues"
+        elif counts.get("Approved", 0) > threshold:
+            verdict = "Approved"
+        else:
+            verdict = "Concerns"
+        # Return a representative card with the voted verdict so concerns/evidence align;
+        # fall back to the first card if none matches (then override just the verdict).
+        for card in cards:
+            if card.verdict == verdict:
+                return card
+        return cards[0].model_copy(update={"verdict": verdict})

package/src/devcouncil/live/signals.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 from datetime import datetime, timezone
 from pathlib import Path
@@ -42,9 +43,8 @@ def write_signal(project_root: Path, client: str, payload: dict[str, Any]) -> Pa
         review_command=_review_command(client.lower(), transcript_path, task_id),
     )
     key = transcript_path or session_id or json.dumps(payload, sort_keys=True, default=str)
-    import hashlib
 
-    digest = hashlib.sha1(key.encode("utf-8", errors="replace")).hexdigest()[:12]
+    digest = hashlib.sha256(key.encode("utf-8", errors="replace")).hexdigest()[:12]
     path = directory / f"{client.lower()}-{digest}.json"
     signal.path = str(path)
     path.write_text(signal.model_dump_json(indent=2) + "\n", encoding="utf-8")

package/src/devcouncil/live/summary.py

@@ -12,8 +12,21 @@ def live_review_summary(project_root: Path, task_id: str | None = None) -> dict:
     signals = load_signals(project_root)
     active_id = active_task_id(project_root)
     scoped_task_id = task_id or active_id
-    blockers = unresolved_blocking_cards(project_root, task_id=scoped_task_id)
+    blockers = unresolved_blocking_cards(project_root, task_id=scoped_task_id, cards=cards)
     pending_signal_items = [signal.model_dump() for signal in signals]
+    open_count = 0
+    resolved_count = 0
+    ignored_count = 0
+    critical_open_count = 0
+    for card in cards:
+        if card.status == "open":
+            open_count += 1
+            if card.verdict == "Critical Issues":
+                critical_open_count += 1
+        elif card.status == "resolved":
+            resolved_count += 1
+        elif card.status == "ignored":
+            ignored_count += 1
     return {
         "active_task_id": active_id,
         "scope_task_id": scoped_task_id,
@@ -21,13 +34,10 @@ def live_review_summary(project_root: Path, task_id: str | None = None) -> dict:
         "pending_signal_items": pending_signal_items[:10],
         "cards": {
             "total": len(cards),
-            "open": len([card for card in cards if card.status == "open"]),
-            "resolved": len([card for card in cards if card.status == "resolved"]),
-            "ignored": len([card for card in cards if card.status == "ignored"]),
-            "critical_open": len([
-                card for card in cards
-                if card.status == "open" and card.verdict == "Critical Issues"
-            ]),
+            "open": open_count,
+            "resolved": resolved_count,
+            "ignored": ignored_count,
+            "critical_open": critical_open_count,
         },
         "blocking_cards": [card.model_dump() for card in blockers],
         "recent_cards": [card.model_dump() for card in cards[:5]],

package/src/devcouncil/live/transcripts.py

@@ -2,10 +2,13 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Any, Iterable
+from typing import Any, Iterable, Literal
 
 from devcouncil.live.models import AgentSession, AgentTurn, session_id_from_path
 
+RoleName = Literal["user", "assistant", "system", "tool", "unknown"]
+KNOWN_ROLES: set[RoleName] = {"user", "assistant", "system", "tool"}
+
 
 CLAUDE_TRANSCRIPT_ROOT = Path.home() / ".claude" / "projects"
 
@@ -28,9 +31,19 @@ def discover_sessions(project_root: Path, client: str = "claude") -> list[AgentS
             client=client,
             transcript_path=str(path),
             updated_at=str(stat.st_mtime),
-            turns=sum(1 for _ in _safe_lines(path)),
+            # len() over the already-materialized splitlines list avoids a
+            # second Python-level pass and matches the previous line count.
+            turns=len(_safe_lines(path)),
         ))
-    return sorted(sessions, key=lambda item: item.updated_at or "", reverse=True)
+    def _updated_key(item: AgentSession) -> float:
+        # updated_at is a stringified mtime; sort numerically so timestamps with
+        # different digit counts (string sort would misorder them) compare correctly.
+        try:
+            return float(item.updated_at or 0.0)
+        except (TypeError, ValueError):
+            return 0.0
+
+    return sorted(sessions, key=_updated_key, reverse=True)
 
 
 def load_turns(path: Path, client: str = "generic") -> list[AgentTurn]:
@@ -47,22 +60,45 @@ def load_turns(path: Path, client: str = "generic") -> list[AgentTurn]:
     return turns
 
 
-def latest_assistant_turn(path: Path, client: str = "generic") -> AgentTurn | None:
+# mtime-keyed cache: reloading and reversing every turn just to find the last
+# assistant message is wasteful when the transcript hasn't changed.
+_LATEST_ASSISTANT_CACHE: dict[str, tuple[float, AgentTurn | None]] = {}
+
+
+def _scan_latest_assistant_turn(path: Path, client: str) -> AgentTurn | None:
     for turn in reversed(load_turns(path, client=client)):
         if turn.role == "assistant":
             return turn
     return None
 
 
+def latest_assistant_turn(path: Path, client: str = "generic") -> AgentTurn | None:
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return _scan_latest_assistant_turn(path, client)
+    key = f"{path}\x00{client}"
+    cached = _LATEST_ASSISTANT_CACHE.get(key)
+    if cached is not None and cached[0] == mtime:
+        return cached[1]
+    result = _scan_latest_assistant_turn(path, client)
+    _LATEST_ASSISTANT_CACHE[key] = (mtime, result)
+    return result
+
+
 def _claude_transcript_candidates(project_root: Path) -> list[Path]:
     local_runtime = project_root / ".devcouncil" / "live" / "claude"
     candidates = list(local_runtime.glob("*.jsonl"))
     if CLAUDE_TRANSCRIPT_ROOT.exists():
         candidates.extend(CLAUDE_TRANSCRIPT_ROOT.rglob("*.jsonl"))
-    return sorted(set(candidates), key=lambda path: path.stat().st_mtime if path.exists() else 0, reverse=True)
+    # Dedup, then sort by path for a deterministic, stat-free order. discover_sessions
+    # re-sorts the resulting sessions by mtime; because that sort is stable, giving it a
+    # deterministic input keeps the tie-break (equal-mtime sessions) stable across runs —
+    # whereas an unordered set would let ties reorder run to run.
+    return sorted(set(candidates))
 
 
-def _safe_lines(path: Path) -> Iterable[str]:
+def _safe_lines(path: Path) -> list[str]:
     try:
         return path.read_text(encoding="utf-8", errors="replace").splitlines()
     except OSError:
@@ -98,18 +134,18 @@ def _turn_from_record(raw: dict[str, Any], session_id: str, turn_index: int, cli
     )
 
 
-def _role(raw: dict[str, Any]) -> str:
+def _role(raw: dict[str, Any]) -> RoleName:
     role = raw.get("role")
     if isinstance(role, str):
-        return role if role in {"user", "assistant", "system", "tool"} else "unknown"
+        return role if role in KNOWN_ROLES else "unknown"
     message = raw.get("message")
     if isinstance(message, dict):
         nested = message.get("role")
         if isinstance(nested, str):
-            return nested if nested in {"user", "assistant", "system", "tool"} else "unknown"
+            return nested if nested in KNOWN_ROLES else "unknown"
     record_type = raw.get("type")
-    if record_type in {"user", "assistant", "system"}:
-        return str(record_type)
+    if record_type in KNOWN_ROLES:
+        return record_type
     return "unknown"