@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/investigating-agentforce-d360/scripts/render_dc.py

@@ -1,1750 +0,0 @@
-"""Render dc._session_summary.md from dc._session_tree.json + dc._session_manifest.json.
-
-Given `DATA_ROOT/<sid>/dc._session_tree.json` (produced by `scripts/assemble_dc.py`)
-this module emits a human-readable `dc._session_summary.md`. Pure tree reader —
-no raw DMO fetches, no joins. The `session.identity` sub-object on the tree
-(added by the assembler) supplies all identity fields; everything else
-(counts, trees, catalog) comes from the tree itself.
-
-Output has 8 `##` sections:
-
-  1. Session identity      — org/agent/bot/planner/session-start/end/duration
-  2. ID reference          — full UUIDs for every ellipsized id in the tree
-  3. Transcript            — narrative USER/AGENT text per TURN
-  4. Complete hierarchical trace — tree with `+start + dur = +end` math
-  5. Per-turn summary      — one row per interaction
-  6. Session counts        — engineer-facing totals
-  7. Empties diagnostics   — DMOs that returned 0 rows + reason
-  8. Catalog (session-filtered)
-
-Contract:
-  - Pure in-memory compute over already-produced artifacts.
-  - Reads DATA_ROOT/<sid>/dc._session_tree.json and dc._session_manifest.json.
-  - UUIDs in the tree are truncated to first 8 chars + `…`; full forms
-    live in the ID reference block.
-  - Session-not-found trees render only Session identity + a note.
-  - Tree schema version check: refuses incompatible versions, warns on
-    missing version (backward compat).
-
-Invocation:
-    python3 scripts/render_dc.py --session <sid>
-"""
-from __future__ import annotations
-
-import argparse
-import html
-import json
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Dict, List, Optional
-
-sys.path.insert(0, str(Path(__file__).parent))
-
-from config import DATA_ROOT, paths
-
-
-# ---- schema ---------------------------------------------------------------
-
-_SUPPORTED_SCHEMA_VERSION = 1
-
-
-# ---- timestamp / string helpers -------------------------------------------
-
-def _parse_iso(s: Optional[str]) -> Optional[datetime]:
-    if not s:
-        return None
-    try:
-        return datetime.fromisoformat(s.replace("Z", "+00:00"))
-    except (ValueError, AttributeError):
-        return None
-
-
-def _fmt_offset(ts_iso: Optional[str], start_dt: Optional[datetime]) -> str:
-    """Return '+12.345s' or '—' if timestamp is missing."""
-    ts = _parse_iso(ts_iso)
-    if ts is None or start_dt is None:
-        return "—"
-    return f"+{(ts - start_dt).total_seconds():.3f}s"
-
-
-def _fmt_duration_ms(start_iso: Optional[str], end_iso: Optional[str]) -> str:
-    s = _parse_iso(start_iso)
-    e = _parse_iso(end_iso)
-    if s is None or e is None:
-        return "—"
-    return f"{int((e - s).total_seconds() * 1000)}ms"
-
-
-def _decode(s: Optional[str]) -> str:
-    if not s:
-        return ""
-    return html.unescape(s).replace("\n", " ").strip()
-
-
-def _truncate(s: Optional[str], n: int = 80) -> str:
-    if not s:
-        return "—"
-    s = _decode(s)
-    return s if len(s) <= n else s[: n - 1] + "…"
-
-
-def _short(uid: Optional[str], keep: int = 8) -> str:
-    """Truncate a UUID to `keep` chars + ellipsis. Full form lives in ID reference."""
-    if not uid:
-        return "—"
-    return uid[:keep] + "…" if len(uid) > keep else uid
-
-
-def _fmt_total_duration(start_iso: Optional[str], end_iso: Optional[str]) -> Optional[str]:
-    s = _parse_iso(start_iso)
-    e = _parse_iso(end_iso)
-    if s is None or e is None:
-        return None
-    total_secs = (e - s).total_seconds()
-    if total_secs >= 3600:
-        h = int(total_secs // 3600)
-        m = int((total_secs % 3600) // 60)
-        return f"{h}h {m}m {total_secs % 60:.3f}s"
-    if total_secs >= 60:
-        m = int(total_secs // 60)
-        return f"{m}m {total_secs % 60:.3f}s"
-    return f"{total_secs:.3f}s"
-
-
-# ---- session-end derivation ----------------------------------------------
-
-def _derive_session_end(sess: dict) -> tuple[Optional[str], Optional[str]]:
-    """Return (effective_end_iso, source_label).
-
-    Contract §3.5 derivation:
-      1. If `session.end_ts` is non-null → return it as-is (caller adds
-         "✓ materialized" suffix).
-      2. Else prefer a SESSION_END interaction's `start_ts`
-         (label: "from SESSION_END interaction").
-      3. Else fall back to the last TURN interaction's `end_ts`
-         (or `start_ts` if end is null) (label: "session still open (last TURN)").
-      4. Else `(None, None)`.
-    """
-    end_iso = sess.get("end_ts")
-    if end_iso:
-        return end_iso, None  # no derivation needed
-    interactions = sess.get("interactions") or []
-    # Prefer SESSION_END start_ts.
-    for iv in interactions:
-        if iv.get("type") == "SESSION_END" and iv.get("start_ts"):
-            return iv["start_ts"], "from SESSION_END interaction"
-    # Fall back to the last TURN (by interaction order; tree is already sorted).
-    last_turn = None
-    for iv in interactions:
-        if iv.get("type") == "TURN":
-            last_turn = iv
-    if last_turn is not None:
-        fallback = last_turn.get("end_ts") or last_turn.get("start_ts")
-        if fallback:
-            return fallback, "session still open (last TURN)"
-    return None, None
-
-
-# ---- section builders -----------------------------------------------------
-
-# Channel-mode value → human cell. Annotated so the reader can tell at
-# a glance why we believe the mode is
-# what it is — `ssot__AiAgentChannelType__c` is identical for MIAW
-# production and Builder Previewer, which makes it useless without the
-# annotation.
-_MODE_HINTS: dict[str, str] = {
-    "production_messaging": "production_messaging  ←  inferred from RelatedMessagingSessionId",
-    "builder_previewer":    "builder_previewer  ←  inferred from VariableText__c bootstrap keys",
-    "voice":                "voice  ←  inferred from RelatedVoiceCallId",
-    "unknown":              "unknown  ←  no signals (headless API, etc.)",
-}
-
-
-def _fmt_mode_cell(mode_value: str) -> str:
-    """Format the `mode` field with a short why-this-value annotation."""
-    return _MODE_HINTS.get(mode_value, mode_value)
-
-
-# Channel values that flag a production messaging session. `VariableText__c`
-# is expected to be NOT_SET on these — the bootstrap variables ride the
-# messaging session record, not the AI session. Any other channel
-# (E & O headless API, Builder Previewer, voice, unknown/integration)
-# can also legitimately produce NOT_SET, but for a different reason
-# (no bootstrap variables were attached at session start) — and we
-# must not mislabel those as "production messaging path".
-_MESSAGING_CHANNELS = frozenset({
-    "SCRT2 - EmbeddedMessaging",
-    "Messaging",
-})
-
-
-def _section_session_bootstrap(identity: dict, channel: Optional[str] = None) -> List[str]:
-    """Render the `bootstrap_variables` block parsed from VariableText__c.
-
-    Three states (all rendered as a small subtable so they don't clutter
-    the main identity table):
-      - None / NOT_SET → "no bootstrap variables for this session"
-                         (with a messaging-path addendum only when the
-                         session's `channel` is actually a messaging
-                         channel — see `_MESSAGING_CHANNELS`).
-      - parse error    → "_parse_error" with the raw prefix
-      - populated      → key/value pairs sorted, plus a "Builder Previewer
-                         indicators" tally derived from the same key set
-                         used in `_derive_mode`.
-
-    Empty section returned when bootstrap_variables is missing entirely
-    (older artifacts predate the bootstrap-variables harvest).
-    """
-    if "bootstrap_variables" not in identity:
-        return []  # older artifact: no bootstrap_variables harvested
-
-    bootstrap = identity.get("bootstrap_variables")
-    lines: List[str] = ["## Session bootstrap", ""]
-
-    if bootstrap is None:
-        if channel in _MESSAGING_CHANNELS:
-            lines.append(
-                "`ssot__VariableText__c` is `NOT_SET` — no bootstrap variables "
-                "(production messaging path; messaging sessions don't carry VariableText)."
-            )
-        else:
-            lines.append(
-                "`ssot__VariableText__c` is `NOT_SET` — no bootstrap variables for this session."
-            )
-        lines.append("")
-        return lines
-
-    if isinstance(bootstrap, dict) and bootstrap.get("_parse_error"):
-        raw = bootstrap.get("_raw") or ""
-        lines.append("`ssot__VariableText__c` failed to parse as JSON:")
-        lines.append("")
-        lines.append("```")
-        lines.append(raw)
-        lines.append("```")
-        lines.append("")
-        return lines
-
-    # Populated case.
-    indicator_keys = {
-        "__resolved_locale__",
-        "__locale_instruction__",
-        "__supports_result_display__",
-        "__show_tool_results_invoked__",
-    }
-    present_indicators = sorted(set(bootstrap) & indicator_keys)
-    indicator_cell = (
-        "yes  ·  " + ", ".join(present_indicators)
-        if present_indicators else "no"
-    )
-
-    lines.append("| Key | Value |")
-    lines.append("|---|---|")
-    for key in sorted(bootstrap):
-        value = bootstrap[key]
-        # Render lists / dicts compactly; keep strings/numbers/bools as-is.
-        if isinstance(value, (list, dict)):
-            value_repr = json.dumps(value)
-        else:
-            value_repr = str(value)
-        # Pipe character would break the markdown table — escape.
-        value_repr = value_repr.replace("|", "\\|")
-        lines.append(f"| {key} | {value_repr} |")
-    lines.append(f"| **Builder Previewer indicators** | {indicator_cell} |")
-    lines.append("")
-    return lines
-
-
-def _compose_agent_cell(identity: dict) -> Optional[str]:
-    """Build the human Agent cell from identity fields; drop None components."""
-    parts: List[str] = []
-    api_name = identity.get("agent_api_name")
-    version = identity.get("agent_version")
-    if api_name and version:
-        parts.append(f"{api_name} {version}")
-    elif api_name:
-        parts.append(api_name)
-    elif version:
-        parts.append(version)
-    label = identity.get("agent_label")
-    if label:
-        parts.append(f"— {label}" if parts else label)
-    atype = identity.get("agent_type")
-    if atype:
-        parts.append(f"({atype})")
-    return " ".join(parts) if parts else None
-
-
-def _fmt_session_end_cell(effective_end_iso: Optional[str],
-                          end_source: Optional[str],
-                          raw_end_iso: Optional[str]) -> Optional[str]:
-    """Compose the identity-table value for `Session end`.
-
-    - Materialized end (`raw_end_iso` truthy)           → "<iso> ✓ materialized"
-    - Derived end   (end_source truthy)                 → "<iso> (<source label>)"
-    - Neither                                           → None (row is dropped)
-    """
-    if effective_end_iso is None:
-        return None
-    if raw_end_iso:
-        return f"{effective_end_iso} ✓ materialized"
-    if end_source:
-        return f"{effective_end_iso} ({end_source})"
-    return effective_end_iso
-
-
-def _section_session_identity(sess: dict, effective_end_iso: Optional[str],
-                              end_source: Optional[str]) -> List[str]:
-    identity = sess.get("identity") or {}
-    org = sess.get("org") or {}
-
-    # `mode` is "production_messaging" / "builder_previewer" / "voice" /
-    # "unknown" — derived in assemble_dc from RelatedMessagingSessionId +
-    # RelatedVoiceCallId + bootstrap_variables because
-    # ssot__AiAgentChannelType__c is identical for MIAW production and
-    # Builder Previewer.
-    mode_value = identity.get("mode")
-    mode_cell = _fmt_mode_cell(mode_value) if mode_value else None
-
-    rows_out = [
-        ("Session id", sess.get("id")),
-        ("Org id", identity.get("org_id")),
-        ("Org alias", org.get("alias")),
-        ("Instance URL", org.get("instance_url")),
-        ("Channel", sess.get("channel")),
-        ("Mode", mode_cell),
-        ("App type", identity.get("app_type")),
-        ("Agent", _compose_agent_cell(identity)),
-        ("Bot id", identity.get("bot_id")),
-        ("Bot name", identity.get("bot_name")),
-        ("Bot version id", identity.get("bot_version_id")),
-        ("Planner id", identity.get("planner_id")),
-        ("Planner name", identity.get("planner_name")),
-        ("Planner type", identity.get("planner_type")),
-        ("Configured model", identity.get("configured_model")),
-        ("Platform user id", identity.get("platform_user_id")),
-        ("Messaging session id", identity.get("messaging_session_id")),
-        ("Messaging end-user id", identity.get("messaging_end_user_id")),
-        ("Voice call id", identity.get("voice_call_id")),
-        ("Individual id", identity.get("individual_id")),
-        ("Session start", sess.get("start_ts")),
-        (
-            "Session end",
-            _fmt_session_end_cell(effective_end_iso, end_source, sess.get("end_ts")),
-        ),
-        ("End type", sess.get("end_type")),
-        ("Total duration", _fmt_total_duration(sess.get("start_ts"), effective_end_iso)),
-    ]
-    lines: List[str] = ["## Session identity", "", "| Field | Value |", "|---|---|"]
-    for label, value in rows_out:
-        if value is None or value == "" or value == "—":
-            continue
-        lines.append(f"| {label} | {value} |")
-    lines.append("")
-    return lines
-
-
-def _section_id_reference(sess: dict) -> List[str]:
-    """Full-UUID lookup for every id the tree truncates."""
-    lines: List[str] = [
-        "## ID reference",
-        "",
-        "The tree truncates UUIDs to the first 8 chars + `…`. Look up the full "
-        "form here. Ordered by type → first occurrence.",
-        "",
-        "```",
-        f"session        = {sess.get('id')}",
-        "",
-    ]
-    # Interactions
-    lines.append("interactions:")
-    for iv in sess.get("interactions", []):
-        lines.append(
-            f"  {iv.get('id')}   type={iv.get('type') or '?'}   "
-            f"trace={iv.get('trace_id') or '—'}"
-        )
-    lines.append("")
-    # Participants
-    lines.append("participants:")
-    for p in sess.get("participants", []):
-        lines.append(
-            f"  {p.get('participant_id') or '—'}   role={p.get('role') or '—'}   "
-            f"agent={p.get('agent_api_name') or '—'}   version={p.get('agent_version') or '—'}   "
-            f"type={p.get('agent_type') or '—'}"
-        )
-    lines.append("")
-
-    # Steps, generations, gateway_requests, messages harvested from the tree.
-    all_steps: List[tuple] = []
-    all_gens: List[tuple] = []
-    all_gws: List[tuple] = []
-    all_msgs: List[tuple] = []
-    for iv in sess.get("interactions", []):
-        for m in iv.get("messages", []):
-            if m.get("message_id"):
-                all_msgs.append((m["message_id"], m.get("role") or m.get("type") or "?"))
-        for st in iv.get("steps", []):
-            if st.get("id"):
-                all_steps.append((st["id"], st.get("type") or "?", st.get("name") or "—"))
-            gen = st.get("generation")
-            if gen and gen.get("generation_id"):
-                all_gens.append((
-                    gen["generation_id"],
-                    gen.get("response_id") or "—",
-                    gen.get("feature") or "—",
-                ))
-            gw = st.get("gateway_request")
-            if gw and gw.get("gateway_request_id"):
-                all_gws.append((
-                    gw["gateway_request_id"], "declared",
-                    gw.get("feature") or "—", gw.get("model") or "—",
-                ))
-        for tb in iv.get("timestamp_bound_gateway_calls", []):
-            if tb.get("gateway_request_id"):
-                all_gws.append((
-                    tb["gateway_request_id"], "timestamp_window",
-                    tb.get("feature") or "—", tb.get("model") or "—",
-                ))
-    for g in sess.get("unbound_gateway_calls", []):
-        if g.get("gateway_request_id"):
-            all_gws.append((
-                g["gateway_request_id"], "unbound",
-                g.get("feature") or "—", g.get("model") or "—",
-            ))
-
-    if all_steps:
-        lines.append("steps:")
-        for sid_, stype, sname in all_steps:
-            lines.append(f"  {sid_}   type={stype}   name={sname}")
-        lines.append("")
-    if all_gens:
-        lines.append("generations:")
-        for gid, rid, feat in all_gens:
-            lines.append(f"  {gid}   response_id={rid}   feature={feat}")
-        lines.append("")
-    if all_gws:
-        lines.append("gateway_requests:")
-        for gwid, bm, feat, model in all_gws:
-            lines.append(f"  {gwid}   binding={bm}   feature={feat}   model={model}")
-        lines.append("")
-    if all_msgs:
-        lines.append("messages:")
-        for mid, role in all_msgs:
-            lines.append(f"  {mid}   role={role}")
-    lines.append("```")
-    lines.append("")
-    return lines
-
-
-def _section_transcript(sess: dict, start_dt: Optional[datetime]) -> List[str]:
-    turns = [iv for iv in sess.get("interactions", []) if iv.get("type") == "TURN"]
-    if not turns:
-        return []
-    lines: List[str] = ["## Transcript", ""]
-    for iv in turns:
-        start_off = _fmt_offset(iv.get("start_ts"), start_dt)
-        dur = _fmt_duration_ms(iv.get("start_ts"), iv.get("end_ts"))
-        lines.append(f"**Interaction {_short(iv.get('id'))}** · {start_off} · {dur}")
-        for m in iv.get("messages", []):
-            role = m.get("role") or m.get("type") or "?"
-            lines.append(f"> **{role}:** {_decode(m.get('text') or '')}")
-        lines.append("")
-    return lines
-
-
-def _section_hierarchical_trace(sess: dict, start_dt: Optional[datetime],
-                                effective_end_iso: Optional[str],
-                                end_source: Optional[str]) -> List[str]:
-    lines: List[str] = [
-        "## Complete hierarchical trace",
-        "",
-        "Notation: `+Xs` = offset in seconds from session start. "
-        "UUIDs are truncated to 8 chars + `…` for readability; "
-        "full forms are in the **ID reference** block above.",
-        "",
-        "```",
-    ]
-
-    # Session header
-    lines.append(f"SESSION {_short(sess.get('id'))}")
-    start_iso = sess.get("start_ts")
-    if start_iso:
-        lines.append(f"│   Start +0.000s ({start_iso})")
-
-    end_iso_raw = sess.get("end_ts")
-    end_type = sess.get("end_type") or None
-    outcome_s = end_type or "—"
-    if not end_type and not end_iso_raw:
-        outcome_s = "—  (session end not yet materialized in STDM)"
-    display_end = end_iso_raw or effective_end_iso
-    if display_end:
-        label_suffix = f"  [{end_source}]" if end_source else ""
-        lines.append(
-            f"│   End   {_fmt_offset(display_end, start_dt)} ({display_end}){label_suffix}  "
-            f"outcome={outcome_s}"
-        )
-    else:
-        lines.append(f"│   End   — (session still open)  outcome={outcome_s}")
-    lines.append("│")
-
-    interactions = sess.get("interactions", [])
-    for iv_idx, iv in enumerate(interactions):
-        is_last_iv = iv_idx == len(interactions) - 1
-        iv_branch = "└──" if is_last_iv else "├──"
-        iv_cont = "    " if is_last_iv else "│   "
-
-        iv_start_off = _fmt_offset(iv.get("start_ts"), start_dt)
-        iv_end_off = _fmt_offset(iv.get("end_ts"), start_dt)
-        iv_dur = _fmt_duration_ms(iv.get("start_ts"), iv.get("end_ts"))
-        iv_type = iv.get("type") or "?"
-        lines.append(
-            f"{iv_branch} {iv_type}  {_short(iv.get('id'))}  "
-            f"{iv_start_off} + {iv_dur} = {iv_end_off}"
-        )
-
-        topic = iv.get("topic")
-        if topic:
-            lines.append(f"{iv_cont}├── TOPIC: {topic}")
-
-        for m in iv.get("messages", []):
-            role = m.get("role") or m.get("type") or "?"
-            m_off = _fmt_offset(m.get("ts"), start_dt) if m.get("ts") else "—"
-            lines.append(f"{iv_cont}├── {role} message  {_short(m.get('message_id'))}  ts={m_off}")
-            lines.append(f"{iv_cont}│   └── text: \"{_truncate(m.get('text'), 100)}\"")
-
-        steps = iv.get("steps", [])
-        tsbound = iv.get("timestamp_bound_gateway_calls", [])
-        tsb_by_step: Dict[str, List[dict]] = {}
-        tsb_interaction_level: List[dict] = []
-        for tb in tsbound:
-            bsid = tb.get("bound_to_step_id")
-            if bsid:
-                tsb_by_step.setdefault(bsid, []).append(tb)
-            else:
-                tsb_interaction_level.append(tb)
-
-        remaining_groups: List[str] = []
-        if steps:
-            remaining_groups.append("steps")
-        if tsb_interaction_level:
-            remaining_groups.append("ts_il")
-
-        for grp_idx, grp in enumerate(remaining_groups):
-            grp_is_last = grp_idx == len(remaining_groups) - 1
-            grp_branch = "└──" if grp_is_last else "├──"
-            grp_cont = "    " if grp_is_last else "│   "
-            if grp == "steps":
-                lines.append(f"{iv_cont}{grp_branch} STEPS:")
-                for st_idx, st in enumerate(steps):
-                    lines.extend(_render_step(
-                        st, st_idx, len(steps), iv_cont, grp_cont,
-                        start_dt, tsb_by_step,
-                    ))
-            else:  # grp == "ts_il"
-                lines.append(f"{iv_cont}{grp_branch} INTERACTION-LEVEL TIMESTAMP-BOUND GATEWAY CALLS:")
-                for tb_idx, tb in enumerate(tsb_interaction_level):
-                    tb_is_last = tb_idx == len(tsb_interaction_level) - 1
-                    tb_branch = "└──" if tb_is_last else "├──"
-                    lines.append(
-                        f"{iv_cont}{grp_cont}{tb_branch} "
-                        f"gateway_request [timestamp_window, interaction-level]  "
-                        f"{_short(tb.get('gateway_request_id'))}  "
-                        f"feature={tb.get('feature') or '—'}  "
-                        f"model={tb.get('model') or '—'}"
-                    )
-
-        if not is_last_iv:
-            lines.append("│")
-
-    # Unbound gateway calls (session root level)
-    ub = sess.get("unbound_gateway_calls", [])
-    if ub:
-        lines.append("")
-        lines.append(
-            f"UNBOUND GATEWAY CALLS ({len(ub)}) — neither declared chain "
-            "nor timestamp window matched"
-        )
-        for i, g in enumerate(ub):
-            branch = "└──" if i == len(ub) - 1 else "├──"
-            lines.append(
-                f"{branch} {_short(g.get('gateway_request_id'))}  "
-                f"feature={g.get('feature') or '—'}  model={g.get('model') or '—'}"
-            )
-
-    lines.append("```")
-    lines.append("")
-    return lines
-
-
-def _render_step(st: dict, st_idx: int, n_steps: int,
-                 iv_cont: str, grp_cont: str,
-                 start_dt: Optional[datetime],
-                 tsb_by_step: Dict[str, List[dict]]) -> List[str]:
-    """Render one step + its nested generation / gateway_request / ts-bound GWs."""
-    st_is_last = st_idx == n_steps - 1
-    st_branch = "└──" if st_is_last else "├──"
-    st_cont = "    " if st_is_last else "│   "
-    st_start_off = _fmt_offset(st.get("start_ts"), start_dt)
-    st_end_off = _fmt_offset(st.get("end_ts"), start_dt)
-    st_dur = _fmt_duration_ms(st.get("start_ts"), st.get("end_ts"))
-
-    # Show the bound LLM model alongside the step name when known.
-    # `model_name` is mirrored from the bound gateway_request by
-    # assemble_dc; None when the declared chain didn't reach or when STDM
-    # dropped writes (the `gateway_requests_dropped_by_stdm` shape).
-    name_cell = st.get("name") or "—"
-    model_name = st.get("model_name")
-    if model_name:
-        name_cell = f"{name_cell} · {model_name}"
-
-    lines = [
-        f"{iv_cont}{grp_cont}{st_branch} {st.get('type') or '?'}  {_short(st.get('id'))}  "
-        f"name={name_cell}  {st_start_off} + {st_dur} = {st_end_off}"
-    ]
-
-    # Step children: error, generation (+ trust signals), gateway_request, collision, bound GWs.
-    step_kids: List[tuple] = []
-    if st.get("error_text"):
-        step_kids.append(("error", None))
-    gen = st.get("generation")
-    if gen:
-        step_kids.append(("gen", gen))
-    gw = st.get("gateway_request")
-    if gw:
-        step_kids.append(("gw", gw))
-    if st.get("gateway_request_collision"):
-        step_kids.append(("collision", None))
-    for tb in tsb_by_step.get(st.get("id", ""), []):
-        step_kids.append(("tsb", tb))
-
-    prefix = f"{iv_cont}{grp_cont}{st_cont}"
-    for k_idx, (ktype, kval) in enumerate(step_kids):
-        k_is_last = k_idx == len(step_kids) - 1
-        k_branch = "└──" if k_is_last else "├──"
-        k_cont = "    " if k_is_last else "│   "
-
-        if ktype == "error":
-            lines.append(f"{prefix}{k_branch} ERROR: {st['error_text']}")
-        elif ktype == "collision":
-            lines.append(
-                f"{prefix}{k_branch} ⚠ gateway_request_collision: "
-                "earlier step claimed the declared GW"
-            )
-        elif ktype == "gen":
-            lines.extend(_render_generation(kval, prefix, k_branch, k_cont,
-                                           step_name=st.get("name")))
-        elif ktype == "gw":
-            lines.extend(_render_gw_declared(kval, prefix, k_branch, k_cont))
-        elif ktype == "tsb":
-            tb = kval
-            lines.append(
-                f"{prefix}{k_branch} gateway_request [timestamp_window]  "
-                f"{_short(tb.get('gateway_request_id'))}  "
-                f"feature={tb.get('feature') or '—'}  "
-                f"model={tb.get('model') or '—'}"
-            )
-    return lines
-
-
-_ROLE_LABELS = {
-    "ReactTopicPrompt":                 "topic-classification output",
-    "ReactInitialPrompt":               "ReAct planner step",
-    "ReactValidationPrompt":            "ReAct validator",
-    "ReactFormatSurfaceResponsePrompt": "response formatter",
-}
-
-
-def _role_label_for(step_name: Optional[str]) -> Optional[str]:
-    if not step_name:
-        return None
-    for key, label in _ROLE_LABELS.items():
-        if key in step_name:
-            return label
-    return None
-
-
-def _parse_finish_reason(response_parameters: Optional[str]) -> Optional[str]:
-    """Pull finish_reason out of the HTML-escaped JSON in responseParameters__c.
-    Shape: `{&quot;finish_reason&quot;:&quot;&#92;&quot;stop&#92;&quot;&quot;,...}`."""
-    if not response_parameters:
-        return None
-    try:
-        decoded = html.unescape(response_parameters)
-        parsed = json.loads(decoded)
-    except (ValueError, TypeError):
-        return None
-    raw = parsed.get("finish_reason") if isinstance(parsed, dict) else None
-    if not isinstance(raw, str):
-        return None
-    # value often comes wrapped in escaped quotes: `\"stop\"` → `stop`
-    return raw.replace("\\", "").strip('"').strip()
-
-
-def _decoded_line(response_text: Optional[str]) -> str:
-    """Render `decoded:` content. Detect tool-call JSON and summarize.
-    responseText__c is HTML-escaped (&quot; etc.) in the wire format — unescape
-    before trying to parse as JSON."""
-    if not response_text:
-        return "—"
-    candidate = html.unescape(response_text).strip()
-    if candidate.startswith("{") and '"toolInvocations"' in candidate:
-        try:
-            obj = json.loads(candidate)
-            tools = obj.get("toolInvocations") or []
-            content = (obj.get("content") or "").strip()
-            if tools:
-                first = tools[0].get("function") or {}
-                name = first.get("name") or "?"
-                args_raw = first.get("arguments") or ""
-                arg_summary = ""
-                try:
-                    args_obj = json.loads(args_raw) if isinstance(args_raw, str) else args_raw
-                    if isinstance(args_obj, dict) and args_obj:
-                        k, v = next(iter(args_obj.items()))
-                        v_str = str(v)
-                        if len(v_str) > 60:
-                            v_str = v_str[:57] + "…"
-                        arg_summary = f'{k}="{v_str}"'
-                except (ValueError, TypeError):
-                    pass
-                prefix = "no user text" if not content else f'"{_truncate(content, 60)}"'
-                n = len(tools)
-                call_word = "tool call" if n == 1 else "tool calls"
-                return f"{prefix}; {n} {call_word} → {name}({arg_summary})"
-        except (ValueError, TypeError):
-            pass
-    return f'"{_truncate(response_text, 140)}"'
-
-
-def _float_or_none(v) -> Optional[float]:
-    try:
-        return float(v)
-    except (ValueError, TypeError):
-        return None
-
-
-def _trust_line(g: dict) -> str:
-    """Summarize trust signals. TOXICITY sub-categories (parented on the
-    quality row) carry a dedicated `safety_score` category in the 0-1 range
-    (1.0 = clean). Non-`safety_score` sub-categories are the 8 hazard axes
-    (profanity, hate, violence, …); report the max of those when a detection
-    fires so the reader sees which axis tripped.
-    Non-TOXICITY detectors (InstructionAdherence, etc.) are parented directly
-    on the generation and render as textual verdicts."""
-    quality = g.get("quality") or []
-    cats = g.get("categories") or []
-    if not quality and not cats:
-        return "—  (no quality/category rows)"
-    parts: List[str] = []
-    for q in quality:
-        subs = q.get("_toxicity_subcategories") or []
-        detected = str(q.get("isToxicityDetected__c", "")).lower() == "true"
-        safety: Optional[float] = None
-        hazard_subs: List[tuple] = []
-        for s in subs:
-            if (s.get("detectorType__c") or "").upper() != "TOXICITY":
-                continue
-            name = s.get("category__c") or ""
-            val = _float_or_none(s.get("value__c"))
-            if val is None:
-                continue
-            if name == "safety_score":
-                safety = val
-            else:
-                hazard_subs.append((name, val))
-        status = "detected" if detected else "clean"
-        safety_str = f"{safety:.2f}" if safety is not None else "—"
-        if not detected and hazard_subs and all(v == 0 for _, v in hazard_subs):
-            detail = f" — all {len(hazard_subs)} sub-categories 0.00"
-        elif hazard_subs:
-            top_name, top_val = max(hazard_subs, key=lambda kv: kv[1])
-            detail = f" — max {top_name}={top_val:.2f}"
-        else:
-            detail = ""
-        parts.append(f"TOXICITY safety_score={safety_str} ({status}{detail})")
-    # Non-TOXICITY detectors (generation-direct).
-    for c in cats:
-        dtype = (c.get("detectorType__c") or "?").strip()
-        if dtype.upper() == "TOXICITY":
-            continue
-        val = c.get("value__c")
-        parts.append(f"{dtype}: {_truncate(val, 80)}")
-    return "; ".join(parts) if parts else "—"
-
-
-def _render_generation(g: dict, prefix: str, k_branch: str, k_cont: str,
-                       *, step_name: Optional[str] = None) -> List[str]:
-    """Generation node: 3 fixed children (decoded / finish_reason+masked / trust).
-    Header is naked (id only); `response_id` and `feature` live in the ID reference
-    block / on the sibling gateway_request line."""
-    lines = [
-        f"{prefix}{k_branch} generation  {_short(g.get('generation_id'))}"
-    ]
-    role = _role_label_for(step_name)
-    decoded = _decoded_line(g.get("response_text"))
-    if role:
-        decoded_line = f"decoded: {decoded}  ({role})"
-    else:
-        decoded_line = f"decoded: {decoded}"
-    masked = g.get("masked_response_text")
-    masked_disp = _truncate(masked, 60) if masked else "—"
-    finish_reason = _parse_finish_reason(g.get("response_parameters")) or "—"
-    gprefix = f"{prefix}{k_cont}"
-    lines.append(f"{gprefix}├── {decoded_line}")
-    lines.append(f"{gprefix}├── finish_reason={finish_reason}  masked={masked_disp}")
-    lines.append(f"{gprefix}└── trust: {_trust_line(g)}")
-    return lines
-
-
-def _render_gw_declared(g: dict, prefix: str, k_branch: str, k_cont: str) -> List[str]:
-    tokens = (
-        f"prompt={int(g.get('prompt_tokens') or 0)}  "
-        f"completion={int(g.get('completion_tokens') or 0)}  "
-        f"total={int(g.get('total_tokens') or 0)}"
-    )
-    tags = g.get("tags") or []
-    md = g.get("metadata") or []
-    recs = g.get("records") or []
-    llm = g.get("llm") or []
-    audit_line = (
-        f"audit: tags={len(tags)}  metadata={len(md)}  records={len(recs)}  llm={len(llm)}"
-        if (tags or md or recs or llm)
-        else "audit: (none)"
-    )
-    return [
-        f"{prefix}{k_branch} gateway_request [declared]  "
-        f"{_short(g.get('gateway_request_id'))}  "
-        f"feature={g.get('feature') or '—'}  "
-        f"model={g.get('model') or '—'}  "
-        f"provider={g.get('provider') or '—'}",
-        f"{prefix}{k_cont}├── tokens: {tokens}",
-        f"{prefix}{k_cont}└── {audit_line}",
-    ]
-
-
-def _section_per_turn_summary(sess: dict, start_dt: Optional[datetime]) -> List[str]:
-    lines: List[str] = [
-        "## Per-turn summary",
-        "",
-        "| Interaction | Type | Start offset | Duration | Steps | "
-        "GW declared | GW ts_window | USER → AGENT |",
-        "|---|---|---|---|---|---|---|---|",
-    ]
-    for iv in sess.get("interactions", []):
-        iv_type = iv.get("type") or "?"
-        start_off = _fmt_offset(iv.get("start_ts"), start_dt)
-        dur = _fmt_duration_ms(iv.get("start_ts"), iv.get("end_ts"))
-        step_count = len(iv.get("steps", []))
-        declared_gws = sum(
-            1 for st in iv.get("steps", [])
-            if st.get("gateway_request")
-            and st["gateway_request"].get("binding_method") == "declared"
-        )
-        tsw_gws = len(iv.get("timestamp_bound_gateway_calls", []))
-        user_msg = next((m for m in iv.get("messages", []) if m.get("role") == "USER"), None)
-        agent_msg = next((m for m in iv.get("messages", []) if m.get("role") == "AGENT"), None)
-        ut = _truncate(user_msg.get("text") if user_msg else None, 40)
-        at = _truncate(agent_msg.get("text") if agent_msg else None, 40)
-        lines.append(
-            f"| `{_short(iv.get('id'))}` | {iv_type} | {start_off} | {dur} | "
-            f"{step_count} | {declared_gws} | {tsw_gws} | {ut} → {at} |"
-        )
-    lines.append("")
-    return lines
-
-
-# ---- visual analysis (mermaid) -------------------------------------------
-
-# Chars that break mermaid label parsing when bare; quote-wrap the string
-# when any of these show up. Underscore+digit tokens in topic strings are
-# legal inside mermaid node labels — only syntax-significant chars need
-# escaping here.
-_MERMAID_LABEL_SPECIALS = set(',()<>:"#')
-
-
-def _escape_mermaid_label(s: str) -> str:
-    if not s:
-        return '""'
-    if any(ch in _MERMAID_LABEL_SPECIALS for ch in s):
-        return '"' + s.replace('"', '\\"') + '"'
-    return s
-
-
-def _sequence_msg(s: str) -> str:
-    """Sanitize free-form text for the right-hand side of a sequenceDiagram
-    arrow. Mermaid parses `A->>B: <text>` up to newline — the text itself is
-    unquoted, so wrapping in `"..."` (as node-label escape does) renders the
-    quotes literally. We just strip newlines and escape the one char that
-    ends the message field (semicolon is the statement terminator)."""
-    if not s:
-        return "—"
-    return s.replace("\n", " ").replace(";", ",").strip()
-
-
-def _flowchart_edge_label(s: str) -> str:
-    """Sanitize free-form text for a flowchart edge label `A -->|label| B`.
-    The delimiter is the pipe itself, so a literal `|` in the label shatters
-    the parser. Square brackets also clash with node-shape syntax. Strip/
-    substitute these; other specials (commas, colons, parens) are fine
-    inside quoted labels, which `_escape_mermaid_label` handles."""
-    if not s:
-        return ""
-    cleaned = s.replace("|", "/").replace("[", "(").replace("]", ")")
-    return _escape_mermaid_label(cleaned)
-
-
-def _step_display_name(st: dict) -> str:
-    """Short, mermaid-safe row label for a step.
-
-    - Strip `AiCopilot__` prefix on LLM prompts.
-    - For ACTION_STEP names shaped `Topic_xxx.AGNT_Action_yyy`, keep the
-      action-name portion after the last `.` so the row reads as the
-      invoked action, not the topic.
-    """
-    name = st.get("name") or st.get("type") or "?"
-    if name.startswith("AiCopilot__"):
-        name = name[len("AiCopilot__"):]
-    if st.get("type") == "ACTION_STEP" and "." in name:
-        name = name.rsplit(".", 1)[-1]
-    # Gantt task names cannot contain colons (task syntax is `label : id, start, dur`).
-    return name.replace(":", "·")
-
-
-def _iter_turns(sess: dict) -> List[dict]:
-    return [iv for iv in sess.get("interactions", []) if iv.get("type") == "TURN"]
-
-
-def _mermaid_gantt(
-    sess: dict,
-    start_dt: Optional[datetime],
-    llm_calls: Optional[List[dict]] = None,
-) -> List[str]:
-    """Gantt chart — wall-clock timeline.
-
-    Rows per turn (ACTION steps tagged :crit). When `llm_calls` is
-    non-empty, a trailing "LLM calls" section renders per-call rows
-    tagged by region-class (:active = cross_region, :done = same-
-    region, plain = unknown). Mermaid's built-in 3-class palette is
-    enough signal for v1; full per-region color would need a classDef
-    block (deferred — see plan OOS-2.A).
-
-    Kill-criterion: <3 total rows after dropping zero-duration steps
-    AND no LLM-call rows → return []. If the step set is thin but the
-    call set is non-empty, we still render (the call rows are the
-    whole point of the overlay).
-    """
-    if start_dt is None:
-        return []
-    rows: List[tuple] = []  # (section_label, row_label, start_ms, end_ms, is_action)
-    turns = _iter_turns(sess)
-    for iv in sess.get("interactions", []):
-        if iv.get("type") != "TURN":
-            continue
-        topic = iv.get("topic") or "(no topic)"
-        section = f"Turn {turns.index(iv) + 1} ({topic})"
-        for st in iv.get("steps", []):
-            if st.get("type") == "SESSION_END":
-                continue
-            s_dt = _parse_iso(st.get("start_ts"))
-            e_dt = _parse_iso(st.get("end_ts"))
-            if s_dt is None or e_dt is None:
-                continue
-            s_ms = int((s_dt - start_dt).total_seconds() * 1000)
-            e_ms = int((e_dt - start_dt).total_seconds() * 1000)
-            if e_ms <= s_ms:
-                continue  # skip zero-duration (e.g. TOPIC_STEP markers)
-            rows.append((section, _step_display_name(st), s_ms, e_ms,
-                         st.get("type") == "ACTION_STEP"))
-
-    # LLM-call rows — one per gateway call, derived from _llm_calls.json.
-    # Rendered in a trailing section so they don't interleave with step
-    # rows (mermaid sections don't sort across boundaries).
-    call_rows: List[tuple] = []  # (row_label, start_ms, end_ms, class_tag)
-    for call in (llm_calls or []):
-        t_iso = call.get("_time")
-        dur_ms = call.get("duration_ms")
-        if not t_iso or dur_ms is None:
-            continue
-        t_dt = _parse_iso(t_iso)
-        if t_dt is None:
-            continue
-        s_ms = int((t_dt - start_dt).total_seconds() * 1000)
-        e_ms = s_ms + int(dur_ms)
-        if e_ms <= s_ms:
-            continue
-        # class_tag: cross_region=True → :active (mermaid's yellow),
-        # cross_region=False → :done (grey), unknown/None → no tag
-        # (default blue). Operators can scan for the yellow bars as
-        # the cross-region outliers.
-        cr = call.get("cross_region")
-        if cr is True:
-            class_tag = ":active, "
-        elif cr is False:
-            class_tag = ":done, "
-        else:
-            class_tag = ":"
-        model = call.get("model_name") or "call"
-        region = call.get("routing_decision") or "—"
-        label = _escape_mermaid_label(f"{model} [{region}]")
-        call_rows.append((label, s_ms, e_ms, class_tag))
-
-    if len(rows) < 3 and not call_rows:
-        return []
-
-    # axisFormat: `%M:%S` renders as minutes:seconds via d3. Our offsets
-    # are ms-from-start passed through `dateFormat x` (unix epoch); d3
-    # treats them as Jan 1 1970 timestamps, so for any session under
-    # 1 hour this reads cleanly as m:ss elapsed. `%L` (ms-of-second)
-    # always rendered 000 because ticks land at second boundaries.
-    # The leading `section anchor` + 1ms milestone forces the x-axis to
-    # start at 00:00 — mermaid derives axis min from the smallest task
-    # timestamp, and without the anchor that's the first step's offset
-    # (~5s into a typical session), making the axis misleadingly slide.
-    lines = [
-        "```mermaid",
-        "gantt",
-        "    title Session timeline (m:ss from start)",
-        "    dateFormat x",
-        "    axisFormat %M:%S",
-        "    section Session start",
-        "    t0 :milestone, 0, 0",
-    ]
-    current_section: Optional[str] = None
-    for section, label, s_ms, e_ms, is_action in rows:
-        if section != current_section:
-            lines.append(f"    section {section}")
-            current_section = section
-        # Mermaid gantt task: `<name> :[tag,] <start>, <end>` — single colon,
-        # tag is the first comma-separated field after it. Two colons (the
-        # `:crit:` shape) is a parse error.
-        prefix = ":crit, " if is_action else ":"
-        lines.append(f"    {label} {prefix}{s_ms}, {e_ms}")
-    if call_rows:
-        lines.append("    section LLM calls")
-        for label, s_ms, e_ms, class_tag in call_rows:
-            lines.append(f"    {label} {class_tag}{s_ms}, {e_ms}")
-    lines.append("```")
-    lines.append("")
-    return lines
-
-
-def _action_short_name(st: dict) -> str:
-    name = st.get("name") or ""
-    if "." in name:
-        name = name.rsplit(".", 1)[-1]
-    return name or "action"
-
-
-def _mermaid_sequence_per_turn(iv: dict, start_dt: Optional[datetime],
-                               turn_no: int) -> List[str]:
-    steps = iv.get("steps", [])
-    has_error = any(st.get("error_text") for st in steps)
-    action_steps = [st for st in steps if st.get("type") == "ACTION_STEP"]
-    if not has_error and len(action_steps) < 2:
-        return []
-
-    topic = iv.get("topic") or "(no topic)"
-    heading = f"### Turn {turn_no} ({topic}) — control flow"
-    lines: List[str] = [heading, "", "```mermaid", "sequenceDiagram"]
-
-    # Participants: U, P, L are always present; actions get A1, A2, …
-    lines.append("    participant U as USER")
-    lines.append("    participant P as Planner")
-    lines.append("    participant L as LLM Gateway")
-    action_alias: Dict[str, str] = {}  # step id → alias
-    for i, st in enumerate(action_steps, start=1):
-        alias = f"A{i}"
-        action_alias[st.get("id") or f"_a{i}"] = alias
-        label = _escape_mermaid_label(_action_short_name(st))
-        lines.append(f"    participant {alias} as {label}")
-
-    # User → Planner (utterance).
-    user_msg = next((m for m in iv.get("messages", []) if m.get("role") == "USER"), None)
-    user_text = _truncate(user_msg.get("text") if user_msg else None, 40)
-    if user_msg:
-        lines.append(f"    U->>P: {_sequence_msg(user_text)}")
-
-    # Walk steps in order. LLM → L, ACTION → A<n>, errors → Note over.
-    for st in steps:
-        stype = st.get("type")
-        if stype == "LLM_STEP":
-            label = _step_display_name(st)
-            gw = st.get("gateway_request") or {}
-            model = gw.get("model")
-            suffix = f" ({model})" if model else ""
-            lines.append(f"    P->>L: {_sequence_msg(label + suffix)}")
-            dur = _fmt_duration_ms(st.get("start_ts"), st.get("end_ts"))
-            if st.get("error_text"):
-                lines.append(f"    Note over L: ERROR in {dur}")
-            else:
-                lines.append(f"    L-->>P: ok ({dur})")
-        elif stype == "ACTION_STEP":
-            alias = action_alias.get(st.get("id") or "", "A?")
-            dur = _fmt_duration_ms(st.get("start_ts"), st.get("end_ts"))
-            lines.append(f"    P->>{alias}: invoke")
-            lines.append(f"    {alias}-->>P: result ({dur})")
-
-    # Agent reply (if any).
-    agent_msg = next((m for m in iv.get("messages", []) if m.get("role") == "AGENT"), None)
-    if agent_msg:
-        agent_text = _truncate(agent_msg.get("text"), 40)
-        lines.append(f"    P-->>U: {_sequence_msg(agent_text)}")
-
-    lines.append("```")
-    lines.append("")
-    return lines
-
-
-def _mermaid_topic_flowchart(sess: dict) -> List[str]:
-    turns = _iter_turns(sess)
-    if not turns:
-        return []
-    # Order-preserving unique topics.
-    topic_ids: Dict[str, str] = {}
-    for iv in turns:
-        t = iv.get("topic") or "(no topic)"
-        if t not in topic_ids:
-            topic_ids[t] = f"T{len(topic_ids) + 1}"
-    if len(topic_ids) == len(turns):
-        return []  # linear — no repeats, skip
-
-    lines: List[str] = ["```mermaid", "flowchart LR"]
-    # Node declarations.
-    for topic, node_id in topic_ids.items():
-        lines.append(f"    {node_id}[{_escape_mermaid_label(topic)}]")
-
-    # Edges: one per turn transition, labelled by the user utterance that
-    # drove into that turn. The first turn has no predecessor so we just
-    # declare the node; edges start from turn 2.
-    prev_topic = turns[0].get("topic") or "(no topic)"
-    for iv in turns[1:]:
-        cur_topic = iv.get("topic") or "(no topic)"
-        user_msg = next((m for m in iv.get("messages", []) if m.get("role") == "USER"), None)
-        utter = _truncate(user_msg.get("text") if user_msg else None, 30)
-        src = topic_ids[prev_topic]
-        dst = topic_ids[cur_topic]
-        label = _flowchart_edge_label(utter) if utter and utter != "—" else ""
-        arrow = f"    {src} -->|{label}| {dst}" if label else f"    {src} --> {dst}"
-        lines.append(arrow)
-        prev_topic = cur_topic
-
-    # Error class for topics whose turn ended with an error_text.
-    errored_topic_ids: List[str] = []
-    for iv in turns:
-        if any(st.get("error_text") for st in iv.get("steps", [])):
-            tid = topic_ids[iv.get("topic") or "(no topic)"]
-            if tid not in errored_topic_ids:
-                errored_topic_ids.append(tid)
-    if errored_topic_ids:
-        lines.append(f"    classDef err fill:#fee,stroke:#c00")
-        for tid in errored_topic_ids:
-            lines.append(f"    class {tid} err")
-
-    lines.append("```")
-    lines.append("")
-    return lines
-
-
-def _mermaid_token_pie(sess: dict) -> List[str]:
-    buckets: Dict[str, int] = {}
-    total = 0
-    for iv in sess.get("interactions", []):
-        for st in iv.get("steps", []):
-            gw = st.get("gateway_request") or {}
-            p = int(gw.get("prompt_tokens") or 0)
-            c = int(gw.get("completion_tokens") or 0)
-            tok = p + c
-            if tok <= 0:
-                continue
-            role = _role_label_for(st.get("name")) or "other"
-            buckets[role] = buckets.get(role, 0) + tok
-            total += tok
-    if total < 1000 or not buckets:
-        return []
-
-    lines = [
-        "```mermaid",
-        "pie showData",
-        f"    title Prompt-role token attribution (total = {total:,})",
-    ]
-    # Largest slice first reads better in most renderers.
-    for role, n in sorted(buckets.items(), key=lambda kv: -kv[1]):
-        lines.append(f'    "{role}" : {n}')
-    lines.append("```")
-    lines.append("")
-    return lines
-
-
-def _section_visual_analysis(
-    sess: dict,
-    start_dt: Optional[datetime],
-    llm_calls: Optional[List[dict]] = None,
-) -> List[str]:
-    blocks: List[List[str]] = []
-    gantt = _mermaid_gantt(sess, start_dt, llm_calls=llm_calls)
-    if gantt:
-        blocks.append(gantt)
-    # Per-turn sequence diagrams (at most one per turn; most turns skip).
-    turns = _iter_turns(sess)
-    for idx, iv in enumerate(turns, start=1):
-        seq = _mermaid_sequence_per_turn(iv, start_dt, idx)
-        if seq:
-            blocks.append(seq)
-    flow = _mermaid_topic_flowchart(sess)
-    if flow:
-        blocks.append(flow)
-    pie = _mermaid_token_pie(sess)
-    if pie:
-        blocks.append(pie)
-
-    if not blocks:
-        return []
-    lines: List[str] = ["## Visual analysis", ""]
-    for b in blocks:
-        lines.extend(b)
-    return lines
-
-
-def _section_session_counts(sess: dict) -> List[str]:
-    c = sess.get("counts", {})
-    st_by_type = c.get("steps_by_type", {})
-    gwb = c.get("gw_binding", {})
-    lines: List[str] = [
-        "## Session counts",
-        "",
-        "| metric | value |",
-        "|---|---|",
-        f"| interactions | {c.get('interactions_total', 0)} |",
-        f"| steps | {c.get('steps_total', 0)} |",
-        f"| llm_steps | {st_by_type.get('LLM_STEP', 0)} |",
-        f"| action_steps | {st_by_type.get('ACTION_STEP', 0)} |",
-        f"| gateway_requests | {c.get('gateway_requests', 0)} |",
-        f"| gateway_responses | {c.get('gateway_responses', 0)} |",
-        f"| 1:1 invariant | {'✓' if c.get('audit_chain_1to1_ok') else '✗'} |",
-        f"| gw declared | {gwb.get('declared', 0)} |",
-        f"| gw timestamp_window | {gwb.get('timestamp_window', 0)} |",
-        f"| gw unbound | {gwb.get('unbound', 0)} |",
-    ]
-    if gwb.get("declared_collisions"):
-        lines.append(f"| ⚠ declared_collisions | {gwb['declared_collisions']} |")
-    lines.append("")
-    return lines
-
-
-def _section_empties_diagnostics(manifest: dict) -> List[str]:
-    """Operator-actionable: lift `_unavailable_reason` verbatim from the manifest."""
-    queries = manifest.get("queries", []) if manifest else []
-    empties = [
-        q for q in queries
-        if q.get("rows") == 0 and q.get("_unavailable_reason")
-    ]
-    if not empties:
-        return []
-    lines: List[str] = [
-        "## Empties diagnostics",
-        "",
-        "DMOs that returned zero rows, with the reason lifted verbatim from the manifest:",
-        "",
-        "| DMO | Reason |",
-        "|---|---|",
-    ]
-    for q in empties:
-        name = q.get("name") or "?"
-        # Pipe characters in reason text would break markdown tables.
-        reason = str(q.get("_unavailable_reason") or "").replace("|", "\\|")
-        lines.append(f"| {name} | {reason} |")
-    lines.append("")
-    return lines
-
-
-def _section_catalog(tree: dict) -> List[str]:
-    catalog = tree.get("catalog", {}) or {}
-    agents = ", ".join(catalog.get("agents_observed", []) or []) or "—"
-    return [
-        "## Catalog (session-filtered)",
-        "",
-        f"- TagDefinitions: {len(catalog.get('tag_definitions', []) or [])}",
-        f"- TagDefinitionAssociations: "
-        f"{len(catalog.get('tag_definition_associations', []) or [])} (agents: {agents})",
-        f"- Tags: {len(catalog.get('tags', []) or [])}",
-        "",
-    ]
-
-
-# ---- top-level render + entry points -------------------------------------
-
-def render(
-    tree: dict,
-    manifest: Optional[dict] = None,
-    session_dir: Optional[Path] = None,
-    *,
-    show_prompts: bool = False,
-) -> str:
-    """Produce the summary markdown for a single session.
-
-    Branches on tree shape:
-    - gateway-direct tree (``_source == "gateway_direct"``) → identity +
-      lag banner + gateway-chain table + per-call detail; skips the
-      Interaction-dependent sections.
-    - minimal tree (session-not-found) → short markdown with just identity.
-    - full tree → multi-section summary (see SKILL.md for the full list).
-
-    ``session_dir`` is reserved for callers that want the renderer to look
-    up artifacts beside the tree on disk. The standalone d360 skill produces
-    no runtime-telemetry rollups — DC alone doesn't expose per-turn LLM
-    latency in a useful form — so when ``None`` (the test-friendly default),
-    the gantt simply draws without the LLM-call overlay.
-
-    ``show_prompts`` (opt-in): when True, the full-tree branch appends
-    a "Planner LLM calls" section with full prompt + response text per
-    LLM call. Default False — the section can add hundreds of KB to the
-    summary on multi-turn sessions.
-
-    Refuses incompatible tree schema versions (see `_assert_schema_version`).
-    """
-    _assert_schema_version(tree)
-
-    # Gateway-direct branch — session resolved but STDM hierarchy hasn't
-    # materialized yet. Handled before the has_interactions check because
-    # the gateway-direct tree does set `session.interactions = []`.
-    if tree.get("_source") == "gateway_direct":
-        return _render_gateway_direct(tree, manifest, show_prompts=show_prompts)
-
-    sess = tree.get("session") or {}
-    sid = sess.get("id") or "<unknown>"
-    has_interactions = "interactions" in sess
-
-    # Minimal-tree early return.
-    if not has_interactions:
-        return _render_minimal(sid, sess)
-
-    start_iso = sess.get("start_ts")
-    start_dt = _parse_iso(start_iso)
-    effective_end_iso, end_source = _derive_session_end(sess)
-
-    # The d360 skill produces no runtime-telemetry rollups — DC alone
-    # doesn't expose per-turn LLM latency in a useful form. Visual
-    # analysis falls back to its pre-rollup output.
-    llm_calls: List[dict] = []
-
-    lines: List[str] = [f"# Session {sid}", ""]
-    lines.extend(_section_session_identity(sess, effective_end_iso, end_source))
-    # VariableText__c bootstrap (channel-mode diagnostic).
-    lines.extend(_section_session_bootstrap(
-        sess.get("identity") or {}, channel=sess.get("channel"),
-    ))
-    lines.extend(_section_id_reference(sess))
-    lines.extend(_section_transcript(sess, start_dt))
-    lines.extend(_section_hierarchical_trace(sess, start_dt, effective_end_iso, end_source))
-    lines.extend(_section_per_turn_summary(sess, start_dt))
-    # Opt-in full prompt + response per LLM call. Off by
-    # default — multi-turn sessions can produce hundreds of KB here.
-    lines.extend(_section_planner_llm_calls(sess, show_prompts=show_prompts))
-    lines.extend(_section_visual_analysis(sess, start_dt, llm_calls=llm_calls))
-    lines.extend(_section_session_counts(sess))
-    lines.extend(_section_empties_diagnostics(manifest or {}))
-    lines.extend(_section_catalog(tree))
-    return "\n".join(lines) + "\n"
-
-
-def _render_minimal(sid: str, sess: dict) -> str:
-    """Short markdown for session-not-found minimal trees."""
-    shape = (sess.get("counts") or {}).get("session_shape", "session_not_found")
-    lines = [
-        f"# Session {sid}",
-        "",
-        "## Session identity",
-        "",
-        "| Field | Value |",
-        "|---|---|",
-        f"| Session id | {sid} |",
-        f"| Session shape | {shape} |",
-        "",
-        "_No interactions resolved in Data Cloud. Check the session id, or wait for "
-        "STDM materialization._",
-        "",
-    ]
-    return "\n".join(lines) + "\n"
-
-
-# Display-only cap on `prompt_text` inside per-call detail. The raw JSON on
-# disk (dc.gateway_requests.json) is authoritative and never truncated — the
-# assembler stores the full prompt, and this slice only applies to markdown.
-_PROMPT_DISPLAY_CAP_BYTES = 65536
-
-
-def _fmt_token_count(value) -> str:
-    """Tolerate ints, stringified ints, and None/''/NOT_SET."""
-    if value in (None, "", "NOT_SET"):
-        return "—"
-    return str(value)
-
-
-def _render_gateway_direct(tree: dict, manifest: Optional[dict],
-                           *, show_prompts: bool = False) -> str:
-    """Render the STDM-hasn't-materialized-yet view.
-
-    Sections:
-      1. Session identity          (reused)
-      2. ID reference              (reused; gracefully handles the empty
-                                    interactions/participants on this path)
-      3. STDM lag banner           (gateway-direct specific)
-      4. Gateway chain table       (gateway-direct specific)
-      5. Per-call detail           (gateway-direct specific)
-      6. Empties diagnostics       (reused; reads manifest, not tree)
-      7. Catalog                   (reused; catalog may be empty on a
-                                    fresh-session gateway-direct tree)
-
-    Skipped: Transcript, Hierarchical trace, Per-turn summary, Session
-    counts — all require Interaction rows that don't exist yet.
-
-    ``show_prompts`` (default False): forwarded to per-call detail so the
-    full prompt block only renders under ``--show-prompts``. The prior
-    behavior unconditionally leaked prompts on this branch, contradicting
-    the documented contract for ``dc._session_summary.md``.
-    """
-    sess = tree.get("session") or {}
-    sid = sess.get("id") or "<unknown>"
-    start_iso = sess.get("start_ts")
-    start_dt = _parse_iso(start_iso)
-    # No derivation needed — sessions.end_ts is the only source on this path.
-    effective_end_iso = sess.get("end_ts")
-
-    lines: List[str] = [f"# Session {sid}", ""]
-    lines.extend(_section_session_identity(sess, effective_end_iso, None))
-    # VariableText__c bootstrap (channel-mode diagnostic).
-    lines.extend(_section_session_bootstrap(
-        sess.get("identity") or {}, channel=sess.get("channel"),
-    ))
-    lines.extend(_section_id_reference(sess))
-    lines.extend(_section_stdm_lag_banner())
-    lines.extend(_section_gateway_chain_table(sess, start_dt))
-    lines.extend(_section_gateway_per_call_detail(sess, show_prompts=show_prompts))
-    lines.extend(_section_empties_diagnostics(manifest or {}))
-    lines.extend(_section_catalog(tree))
-    return "\n".join(lines) + "\n"
-
-
-def _section_stdm_lag_banner() -> List[str]:
-    return [
-        "## STDM materialization lag",
-        "",
-        "> **Note** STDM Interaction/Step/Message DMOs have not yet "
-        "materialized for this session. The view below is the gateway chain "
-        "harvested directly from Gateway DMOs (materialize in minutes). "
-        "Re-run in 24–72h for the full hierarchical trace.",
-        "",
-    ]
-
-
-def _section_gateway_chain_table(sess: dict,
-                                 start_dt: Optional[datetime]) -> List[str]:
-    chain = sess.get("gateway_chain") or []
-    lines: List[str] = [
-        "## Gateway chain",
-        "",
-        "| # | Request ts | Model | Provider | Prompt template | "
-        "Prompt tok | Completion tok | Total tok | Response ts |",
-        "|---|---|---|---|---|---|---|---|---|",
-    ]
-    for i, call in enumerate(chain, start=1):
-        req_offset = _fmt_offset(call.get("timestamp"), start_dt)
-        resp_offset = _fmt_offset(
-            (call.get("response") or {}).get("timestamp"), start_dt)
-        model = call.get("model") or "—"
-        provider = call.get("provider") or "—"
-        template = call.get("prompt_template_dev_name") or "—"
-        prompt_tok = _fmt_token_count(call.get("prompt_tokens"))
-        completion_tok = _fmt_token_count(call.get("completion_tokens"))
-        total_tok = _fmt_token_count(call.get("total_tokens"))
-        lines.append(
-            f"| {i} | {req_offset} | {model} | {provider} | {template} | "
-            f"{prompt_tok} | {completion_tok} | {total_tok} | {resp_offset} |"
-        )
-    lines.append("")
-    return lines
-
-
-def _pick_fence(text: str) -> str:
-    """Pick a backtick fence long enough to wrap `text` safely.
-
-    CommonMark lets a fenced code block use any run of 3+ backticks; the
-    closing fence must be at least as long as the opening. LLM prompts
-    routinely contain triple-backticks inside tool-use examples, so a
-    hardcoded ``` fence closes early and corrupts the rest of the doc.
-    """
-    if not isinstance(text, str) or not text:
-        return "```"
-    longest = 0
-    run = 0
-    for ch in text:
-        if ch == "`":
-            run += 1
-            if run > longest:
-                longest = run
-        else:
-            run = 0
-    return "`" * max(3, longest + 1)
-
-
-def _capped_payload(text: Optional[str], note_source: str) -> tuple[str, bool, str]:
-    """Cap a payload string at `_PROMPT_DISPLAY_CAP_BYTES` for display.
-
-    Returns ``(body, truncated, source_note)``. Byte-length check so
-    multi-byte chars don't blow through the limit when the renderer emits
-    UTF-8 text. Slicing happens on the encoded form, then decodes with
-    ``errors="ignore"`` so we never split a multi-byte char mid-sequence.
-    `source_note` names the on-disk file with the authoritative full text.
-    """
-    if not isinstance(text, str) or not text:
-        return ("(empty)", False, note_source)
-    encoded = text.encode("utf-8")
-    if len(encoded) <= _PROMPT_DISPLAY_CAP_BYTES:
-        return (text, False, note_source)
-    body = encoded[:_PROMPT_DISPLAY_CAP_BYTES].decode("utf-8", errors="ignore")
-    return (body, True, note_source)
-
-
-def _render_call_detail_block(call: dict, idx: int, *,
-                              show_prompts: bool = False,
-                              show_response_text: bool = False) -> List[str]:
-    """Render one ``#### LLM call N — <short-id>`` block.
-
-    Used by both:
-      - the gateway-direct branch (``_section_gateway_per_call_detail``)
-      - the full-tree opt-in section (``_section_planner_llm_calls``)
-
-    ``call`` shape (subset of fields used here):
-      gateway_request_id, model, provider, prompt_template_dev_name,
-      prompt_tokens, completion_tokens, total_tokens, prompt_text,
-      response (-> finish_reason), response_text (only on full-tree path).
-
-    The prompt and response blocks are independently gated:
-      - ``show_prompts`` controls the **Prompt** block.
-      - ``show_response_text`` controls the **Response** block (full-tree
-        only — gateway-direct chain entries don't carry response_text).
-    Both default off so callers must opt in explicitly. The summary line
-    (model/provider/template/tokens/finish_reason) always renders.
-    """
-    gw_id = call.get("gateway_request_id") or "—"
-    short_id = _short(gw_id)
-    lines = [f"#### LLM call {idx} — {short_id}", ""]
-    finish_reason = (call.get("response") or {}).get("finish_reason") or "—"
-    summary = (
-        f"- model={call.get('model') or '—'}"
-        f"  provider={call.get('provider') or '—'}"
-        f"  template={call.get('prompt_template_dev_name') or '—'}"
-        f"  prompt_tok={_fmt_token_count(call.get('prompt_tokens'))}"
-        f"  completion_tok={_fmt_token_count(call.get('completion_tokens'))}"
-        f"  total_tok={_fmt_token_count(call.get('total_tokens'))}"
-        f"  finish_reason={finish_reason}"
-    )
-    lines.append(summary)
-    lines.append("")
-
-    # Prompt block — gated by show_prompts. Default-off everywhere; the
-    # summary file should never leak full prompt text without an explicit
-    # --show-prompts opt-in (matches the doc contract in SKILL.md).
-    if show_prompts:
-        body, truncated, src = _capped_payload(
-            call.get("prompt_text"), "dc.gateway_requests.json")
-        fence = _pick_fence(body)
-        lines.append("**Prompt** (full input sent to the model):")
-        lines.append(fence)
-        lines.append(body)
-        if truncated:
-            lines.append(f"…[truncated; full prompt in {src}]")
-        lines.append(fence)
-        lines.append("")
-
-    # Response block — only the full-tree path carries response_text;
-    # gateway-direct rows get finish_reason in the header line above and
-    # nothing else (the response DMO doesn't carry text on that path).
-    if show_response_text:
-        body, truncated, src = _capped_payload(
-            call.get("response_text"), "dc.generations.json")
-        # html.unescape so the rendered block reads as plain JSON instead of
-        # &quot;-laden text — matches the existing _decoded_line treatment.
-        if body and body != "(empty)":
-            body = html.unescape(body)
-        fence = _pick_fence(body)
-        lines.append("**Response** (model output, including tool invocations):")
-        lines.append(fence)
-        lines.append(body)
-        if truncated:
-            lines.append(f"…[truncated; full response in {src}]")
-        lines.append(fence)
-        lines.append("")
-
-    return lines
-
-
-def _section_gateway_per_call_detail(sess: dict, *,
-                                     show_prompts: bool = False) -> List[str]:
-    """Per-call detail for the gateway-direct branch.
-
-    ``gateway_chain`` does NOT carry `response_text` (the responses DMO
-    doesn't include it on that path), so the response block is always
-    suppressed. The prompt block is gated by ``show_prompts`` so the
-    default summary doesn't leak full prompt text — matches the
-    documented contract for ``dc._session_summary.md``.
-    """
-    chain = sess.get("gateway_chain") or []
-    lines: List[str] = ["## Per-call detail", ""]
-    for i, call in enumerate(chain, start=1):
-        lines.extend(_render_call_detail_block(
-            call, i, show_prompts=show_prompts, show_response_text=False))
-    return lines
-
-
-def _collect_planner_llm_calls(sess: dict) -> List[dict]:
-    """Walk ``interactions[].steps[]`` and collect call-view dicts.
-
-    Each step that has a ``gateway_request`` (regardless of binding method)
-    contributes one call view. ``response_text`` is sourced from the step's
-    sibling ``generation.response_text`` when present; otherwise the call is
-    still emitted with the prompt + token summary.
-
-    Returned dicts use the same field names as ``gateway_chain`` entries so
-    ``_render_call_detail_block`` can consume both shapes uniformly.
-    """
-    calls: List[dict] = []
-    for iv in sess.get("interactions") or []:
-        for st in iv.get("steps") or []:
-            gw = st.get("gateway_request")
-            if not gw:
-                continue
-            gen = st.get("generation") or {}
-            calls.append({
-                "gateway_request_id": gw.get("gateway_request_id"),
-                "model": gw.get("model"),
-                "provider": gw.get("provider"),
-                "prompt_template_dev_name": gw.get("prompt_template_dev_name"),
-                "prompt_tokens": gw.get("prompt_tokens"),
-                "completion_tokens": gw.get("completion_tokens"),
-                "total_tokens": gw.get("total_tokens"),
-                "prompt_text": gw.get("prompt_text"),
-                "response": gw.get("response"),
-                "response_text": gen.get("response_text"),
-            })
-    return calls
-
-
-def _section_planner_llm_calls(sess: dict, *, show_prompts: bool) -> List[str]:
-    """Opt-in full-tree section showing the input prompt + response
-    for every LLM call in the session's hierarchical trace.
-
-    Off by default — prompts can be 30 KB+ each on multi-turn sessions
-    and would otherwise dominate the summary. Enable with
-    ``render_dc.py --show-prompts``.
-    """
-    if not show_prompts:
-        return []
-    calls = _collect_planner_llm_calls(sess)
-    if not calls:
-        return []
-    lines: List[str] = [
-        "## Planner LLM calls (full prompts + responses)",
-        "",
-        f"_Found {len(calls)} LLM call(s) across the session's hierarchical "
-        f"trace. Prompts are capped at "
-        f"{_PROMPT_DISPLAY_CAP_BYTES // 1024} KB for display; full payloads "
-        f"are on disk in `dc.gateway_requests.json` and "
-        f"`dc.generations.json`._",
-        "",
-    ]
-    for i, call in enumerate(calls, start=1):
-        # show_prompts is True here by section-guard above (early return when
-        # show_prompts is False); pass through explicitly so the helper's new
-        # prompt-gate stays aligned with the section's intent.
-        lines.extend(_render_call_detail_block(
-            call, i, show_prompts=True, show_response_text=True))
-    return lines
-
-
-def _assert_schema_version(tree: dict) -> None:
-    """Refuse unsupported versions; warn on missing version (older assembler)."""
-    version = (tree.get("session") or {}).get("_schema_version")
-    if version is None:
-        print(
-            "render_dc: WARN tree has no _schema_version "
-            "(produced by an older assembler?); rendering anyway",
-            file=sys.stderr,
-        )
-        return
-    if version != _SUPPORTED_SCHEMA_VERSION:
-        raise SystemExit(
-            f"render_dc: unsupported tree _schema_version={version}; "
-            f"expected {_SUPPORTED_SCHEMA_VERSION}"
-        )
-
-
-def main_for_session(sid: str, *, show_prompts: bool = False) -> int:
-    """Read session tree + manifest from the nested session dir; emit summary.md.
-
-    Uses ``assemble_dc._find_session_dir`` to locate the session under
-    ``DATA_ROOT/<org>/<agent>__<ver>/<sid>/`` — follows the ``_sessions/*.link``
-    breadcrumb when present, globs otherwise. No callers need to know the
-    full identity triple upfront.
-
-    ``show_prompts``: pass through to ``render`` to include the
-    opt-in "Planner LLM calls" section.
-    """
-    from assemble_dc import _find_session_dir
-    session_dir = _find_session_dir(sid)
-    tree_path = session_dir / "dc._session_tree.json"
-    if not tree_path.is_file():
-        raise SystemExit(
-            f"render_dc: tree not found at {tree_path}; "
-            f"run `python3 scripts/assemble_dc.py --session {sid}` first"
-        )
-    manifest_path = session_dir / "dc._session_manifest.json"
-    manifest: Optional[dict] = None
-    if manifest_path.is_file():
-        try:
-            manifest = json.loads(manifest_path.read_text())
-        except (json.JSONDecodeError, OSError) as e:
-            print(
-                f"render_dc: WARN could not read manifest: {str(e).splitlines()[0]}",
-                file=sys.stderr,
-            )
-
-    tree = json.loads(tree_path.read_text())
-    _assert_schema_version(tree)
-
-    md_path = session_dir / "dc._session_summary.md"
-    md_path.write_text(render(tree, manifest, session_dir=session_dir,
-                              show_prompts=show_prompts))
-    print(f"render_dc: wrote {md_path}", file=sys.stderr)
-    return 0
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(
-        prog="render_dc.py",
-        description="Render dc._session_summary.md from dc._session_tree.json for one session.",
-    )
-    ap.add_argument("--session", required=True,
-                    help="AI-agent session UUID or MessagingSession id (0Mw...). "
-                         "Messaging ids are resolved from disk "
-                         "(DATA_ROOT/*/dc.sessions.json); run fetch_dc.py first "
-                         "if the session hasn't been fetched yet.")
-    ap.add_argument("--show-prompts", action="store_true",
-                    help="Include the opt-in 'Planner LLM calls' section "
-                         "with the full input prompt + response per LLM call. "
-                         "Off by default — multi-turn sessions can produce "
-                         "hundreds of KB here. Per-prompt display is capped "
-                         "at 64 KB; full payloads remain on disk in "
-                         "dc.gateway_requests.json + dc.generations.json.")
-    # Runtime-agnostic path overrides; default to ~/.vibe/...
-    from _shared.cli_override import add_cli_flags, apply_overrides
-    add_cli_flags(ap)
-    args = ap.parse_args()
-    apply_overrides(args, caller_globals=globals())
-    from resolve_session import resolve_disk_or_live
-    sid = resolve_disk_or_live(args.session)
-    return main_for_session(sid, show_prompts=args.show_prompts)
-
-
-if __name__ == "__main__":
-    sys.exit(main())