Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-d360-analyze

agentforce-d360-analyze

Verified

Data Cloud 360° view of a single Agentforce session. TRIGGER when user asks to trace, inspect, summarize, or describe a specific Agentforce session by session id (Agent Session UUID `019d…` or MessagingSession id `0Mw…`). Also triggers on session discovery — find/list/search sessions by time, agent, channel, outcome, or conversation text — when the user has no session id yet. DO NOT TRIGGER for design-time architecture questions (use agentforce-architecture-analyze instead) or for runtime perf/latency/SLO questions that require platform telemetry beyond Data Cloud.

FileKindSize
README.mdmarkdown6.2 KB
SKILL.mdskill md13.2 KB
assets/dc/app_generation.sqlother1.9 KB
assets/dc/content_category.sqlother1.5 KB
assets/dc/content_quality.sqlother1.3 KB
assets/dc/discover_sessions.sqlother2.3 KB
assets/dc/feedback.sqlother1.5 KB
assets/dc/feedback_details.sqlother1.3 KB
assets/dc/gateway_records.sqlother1.6 KB
assets/dc/gateway_request_llm.sqlother1.6 KB
assets/dc/gateway_request_metadata.sqlother1.5 KB
assets/dc/gateway_request_tags.sqlother1.4 KB
assets/dc/gateway_requests.sqlother3.4 KB
assets/dc/gateway_responses.sqlother1.7 KB
assets/dc/generations.sqlother1.9 KB
assets/dc/interactions.sqlother2.0 KB
assets/dc/messages.sqlother2.1 KB
assets/dc/messaging_session.sqlother1.7 KB
assets/dc/moment_interactions.sqlother1.4 KB
assets/dc/moments.sqlother1.5 KB
assets/dc/participants.sqlother1.8 KB
assets/dc/sessions.sqlother3.0 KB
assets/dc/steps.sqlother2.6 KB
assets/dc/tag_associations.sqlother1.7 KB
assets/dc/tag_definition_associations.sqlother1.4 KB
assets/dc/tag_definitions.sqlother1.8 KB
assets/dc/tags.sqlother1.3 KB
assets/dc/telemetry_spans.sqlother2.1 KB
references/artifacts.mdmarkdown2.7 KB
references/dc_dmo_fields.mdmarkdown42.1 KB
references/dc_pipeline_contract.mdmarkdown26.3 KB
scripts/_shared/__init__.pyscript122 B
scripts/_shared/cli_override.pyscript3.3 KB
scripts/_shared/fs_guard.pyexecutablescript13.2 KB
scripts/_shared/paths.pyscript5.8 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript548 B
scripts/assemble_dc.pyscript69.6 KB
scripts/config.pyscript1.8 KB
scripts/dc.pyscript13.8 KB
scripts/discover_sessions.pyscript21.1 KB
scripts/fetch_dc.pyscript45.1 KB
scripts/render_dc.pyscript69.7 KB
scripts/resolve_session.pyscript10.8 KB
scripts/storage.pyscript3.1 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript483 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/synthetic_session.pyscript14.6 KB
scripts/tests/test_assemble_dc_bootstrap_and_mode.pyscript4.2 KB
scripts/tests/test_assemble_dc_gateway_direct.pyscript8.3 KB
scripts/tests/test_assemble_dc_gateway_direct_integration.pyscript6.4 KB
scripts/tests/test_assemble_dc_helpers.pyscript10.0 KB
scripts/tests/test_assemble_dc_integration.pyscript9.3 KB
scripts/tests/test_dc_and_resolve_session.pyscript26.7 KB
scripts/tests/test_default_target_org.pyscript18.8 KB
scripts/tests/test_discover_sessions.pyscript19.0 KB
scripts/tests/test_discover_sessions_grep_ci.pyscript8.2 KB
scripts/tests/test_fetch_dc_helpers.pyscript10.6 KB
scripts/tests/test_fetch_dc_identity.pyscript22.0 KB
scripts/tests/test_fetch_dc_main.pyscript9.4 KB
scripts/tests/test_fetch_dc_waterfall.pyscript8.6 KB
scripts/tests/test_fetch_dc_waterfall_full.pyscript11.2 KB
scripts/tests/test_identity_coherence.pyscript13.8 KB
scripts/tests/test_render_dc_branches.pyscript9.9 KB
scripts/tests/test_render_dc_gateway_direct.pyscript5.1 KB
scripts/tests/test_render_dc_helpers.pyscript10.5 KB
scripts/tests/test_render_dc_integration.pyscript7.7 KB
scripts/tests/test_render_dc_planner_llm_calls.pyscript11.8 KB
scripts/tests/test_render_dc_show_prompts_gating.pyscript8.7 KB
scripts/tests/test_resolve_from_disk.pyscript4.1 KB
scripts/tests/test_resolve_session_main.pyscript5.2 KB
scripts/tests/test_runtime_override.pyscript4.2 KB
scripts/tests/test_session_shape.pyscript3.5 KB
scripts/tests/test_session_shape_dropped_by_stdm.pyscript3.5 KB
scripts/tests/test_skill_md_prefix_block.pyscript6.8 KB

scripts/render_dc.py

View on GitHub
"""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())
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall