Sf Ai Agentforce Observability

# Network capture data — contains session tokens, org URLs, and client-specific content
captures/
*.har

# Python
__pycache__/
*.pyc
.trace-venv/

# Dev-only test harness (contains hardcoded org references)
scripts/test_v65.py

# Output data
stdm_data/
*.parquet
trace-results/

# Builder URL cache (contains org-specific URLs)
.builder-url-cache.json

# Debug screenshots
debug-*.png


#!/usr/bin/env python3
"""
Message Timeline Analysis Template

Reconstructs conversation timelines for debugging agent behavior.
Shows all messages and steps in chronological order for a session.

Usage:
    python3 message-timeline.py --data-dir ./stdm_data --session-id "a0x..."
    python3 message-timeline.py --data-dir ./stdm_data --list-failed

Output includes:
- Chronological message flow
- Step details (LLM reasoning, action inputs/outputs)
- Topic transitions
- Timing information
"""

import argparse
import json
from pathlib import Path
from datetime import datetime

import polars as pl
from rich.console import Console
from rich.panel import Panel
from rich.text import Text

console = Console()


def load_data(data_dir: Path) -> dict:
    """Load all STDM entities as lazy frames."""
    return {
        "sessions": pl.scan_parquet(data_dir / "sessions" / "**/*.parquet"),
        "interactions": pl.scan_parquet(data_dir / "interactions" / "**/*.parquet"),
        "steps": pl.scan_parquet(data_dir / "steps" / "**/*.parquet"),
        "messages": pl.scan_parquet(data_dir / "messages" / "**/*.parquet"),
    }


def get_session_info(data: dict, session_id: str) -> dict:
    """Get session metadata."""
    session = (
        data["sessions"]
        .filter(pl.col("ssot__Id__c") == session_id)
        .collect()
    )

    if session.is_empty():
        return None

    row = session.row(0, named=True)
    return {
        "id": row.get("ssot__Id__c"),
        "agent": row.get("ssot__AiAgentApiName__c", "Unknown"),
        "start": row.get("ssot__StartTimestamp__c"),
        "end": row.get("ssot__EndTimestamp__c"),
        "end_type": row.get("ssot__AiAgentSessionEndType__c"),
    }


def get_timeline(data: dict, session_id: str) -> list:
    """Build chronological timeline of events."""
    # Get interactions for this session
    interactions = (
        data["interactions"]
        .filter(pl.col("ssot__AiAgentSessionId__c") == session_id)
        .collect()
    )

    interaction_ids = interactions["ssot__Id__c"].to_list()

    # Get messages
    messages = (
        data["messages"]
        .filter(pl.col("ssot__AiAgentInteractionId__c").is_in(interaction_ids))
        .collect()
    )

    # Get steps
    steps = (
        data["steps"]
        .filter(pl.col("ssot__AiAgentInteractionId__c").is_in(interaction_ids))
        .collect()
    )

    # Build timeline
    timeline = []

    # Add messages
    for row in messages.iter_rows(named=True):
        timeline.append({
            "type": "message",
            "timestamp": row.get("ssot__MessageSentTimestamp__c", ""),
            "interaction_id": row.get("ssot__AiAgentInteractionId__c"),
            "message_type": row.get("ssot__AiAgentInteractionMessageType__c"),
            "content": row.get("ssot__ContentText__c", ""),
        })

    # Add steps
    for row in steps.iter_rows(named=True):
        timeline.append({
            "type": "step",
            "timestamp": "",  # Steps don't have timestamps
            "interaction_id": row.get("ssot__AiAgentInteractionId__c"),
            "step_type": row.get("ssot__AiAgentInteractionStepType__c"),
            "name": row.get("ssot__Name__c"),
            "input": row.get("ssot__InputValueText__c"),
            "output": row.get("ssot__OutputValueText__c"),
        })

    # Add interactions (for topic info)
    for row in interactions.iter_rows(named=True):
        timeline.append({
            "type": "interaction",
            "timestamp": row.get("ssot__StartTimestamp__c", ""),
            "interaction_id": row.get("ssot__Id__c"),