@agenthippo-ai/agenthippo 1.110.11 → 1.110.19

package/out/base-prompts/skills/spotlight-visualize/scripts/query-analytics.sh

@@ -1,2551 +0,0 @@
-#!/usr/bin/env bash
-#
-# Copyright (c) AgentHippo.ai. All rights reserved.
-#
-# Query AgentHippo Analytics with DuckDB
-#
-# Run with --help for full usage. Key queries:
-#
-#   Cost:      --cost, --cost-by-session, --cost-by-model, --cost-by-pack
-#   Debug:     --session <id>, --request <id>, --latest-session
-#               --session-messages <id> (parse messages directly from traces)
-#   Regress:   --compare-versions <agent>, --top-sessions <agent>
-#   Health:    --problems, --errors, --largest-requests, --tool-loops <id>
-#   Custom:    --sql "SELECT ..." (can use ${BASE_QUERY} and ${EXTRACT_ATTRS} CTEs)
-#
-
-set -euo pipefail
-
-# AGENT_HOME_DIR is set by the extension with the branded directory path
-# Falls back to ~/.agent-hippo for manual script runs
-AGENT_HOME_DIR="${AGENT_HOME_DIR:-$HOME/.agent-hippo}"
-ANALYTICS_DIR="${AGENT_HOME_DIR}/analytics"
-BIN_DIR="${AGENT_HOME_DIR}/bin"
-# Prefer explicit traces dir from dashboard env; fall back to default analytics path.
-TRACES_DIR="${AGENTIDE_TRACES_DIR:-${ANALYTICS_DIR}/traces}"
-INDEX_DB_PATH="${AGENTIDE_INDEX_DB_PATH:-${TRACES_DIR}/analytics.duckdb}"
-TMP_DIR="${AGENTIDE_ANALYTICS_TMP_DIR:-${ANALYTICS_DIR}/tmp}"
-MESSAGE_PREVIEW_CHARS="${AGENTIDE_SPOTLIGHT_MESSAGE_PREVIEW_CHARS:-800}"
-MESSAGE_PART_PREVIEW_CHARS="${AGENTIDE_SPOTLIGHT_MESSAGE_PART_PREVIEW_CHARS:-400}"
-MESSAGE_OUTPUT_BUDGET_CHARS="${AGENTIDE_SPOTLIGHT_OUTPUT_BUDGET_CHARS:-12000}"
-TRACE_EVENT_PREVIEW_LIMIT="${AGENTIDE_SPOTLIGHT_TRACE_EVENT_PREVIEW_LIMIT:-12}"
-SESSION_DEBUG_REQUEST_LIMIT="${AGENTIDE_SPOTLIGHT_SESSION_DEBUG_REQUEST_LIMIT:-6}"
-SESSION_DEBUG_TOOL_LIMIT="${AGENTIDE_SPOTLIGHT_SESSION_DEBUG_TOOL_LIMIT:-8}"
-
-# Find duckdb binary
-# Use indexed DB when available for fast session/message queries.
-find_duckdb() {
-    if command -v duckdb &> /dev/null; then
-        echo "duckdb"
-    elif [[ -x "${BIN_DIR}/duckdb" ]]; then
-        echo "${BIN_DIR}/duckdb"
-    else
-        echo "ERROR: DuckDB not found. Run install-analytics.sh first." >&2
-        exit 1
-    fi
-}
-
-DUCKDB=$(find_duckdb)
-
-# Check if traces exist
-check_traces() {
-    if ! ls "${TRACES_DIR}"/*.jsonl &> /dev/null; then
-        echo "No trace files found in ${TRACES_DIR}/"
-        echo "Make sure OTEL Collector is running and LiteLLM has the 'otel' callback enabled."
-        exit 0
-    fi
-}
-
-has_indexed_db() {
-    if [[ ! -f "${INDEX_DB_PATH}" ]]; then
-        return 1
-    fi
-
-    local table_count
-    table_count="$(${DUCKDB} -readonly "${INDEX_DB_PATH}" -csv -c "
-        SELECT COUNT(DISTINCT table_name)
-        FROM information_schema.tables
-        WHERE table_name IN ('model_calls', 'sessions', 'turns');
-    " 2>/dev/null | tail -n 1)"
-
-    [[ "${table_count}" == "3" ]]
-}
-
-has_indexed_table() {
-    local table_name="$1"
-    if [[ ! -f "${INDEX_DB_PATH}" ]]; then
-        return 1
-    fi
-    local found
-    found="$(${DUCKDB} -readonly "${INDEX_DB_PATH}" -csv -c "
-        SELECT COUNT(*)
-        FROM information_schema.tables
-        WHERE table_name = '$(escape_sql_literal "${table_name}")';
-    " 2>/dev/null | tail -n 1)"
-    [[ "${found}" == "1" ]]
-}
-
-run_duckdb_sql() {
-    local sql="$1"
-    if [[ -f "${INDEX_DB_PATH}" ]]; then
-        ${DUCKDB} -readonly "${INDEX_DB_PATH}" -c "${sql}"
-    else
-        ${DUCKDB} -c "${sql}"
-    fi
-}
-
-run_duckdb_json_sql() {
-    local sql="$1"
-    if [[ -f "${INDEX_DB_PATH}" ]]; then
-        ${DUCKDB} -readonly "${INDEX_DB_PATH}" -json -c "${sql}"
-    else
-        ${DUCKDB} -json -c "${sql}"
-    fi
-}
-
-escape_sql_literal() {
-    local value="${1:-}"
-    printf "%s" "${value//\'/'\'}"
-}
-
-sanitize_artifact_label() {
-    local value="${1:-artifact}"
-    printf "%s" "${value}" | tr -cs 'A-Za-z0-9._-' '_'
-}
-
-ensure_tmp_dir() {
-    mkdir -p "${TMP_DIR}"
-}
-
-make_artifact_path() {
-    local prefix="${1:-spotlight-query}"
-    local suffix="${2:-txt}"
-    local path
-    ensure_tmp_dir
-    path="$(mktemp "${TMP_DIR}/$(sanitize_artifact_label "${prefix}")-XXXXXX")"
-    if [[ -n "${suffix}" ]]; then
-        mv "${path}" "${path}.${suffix}"
-        path="${path}.${suffix}"
-    fi
-    printf "%s\n" "${path}"
-}
-
-format_messages_rows() {
-    python3 -c '
-import os
-import json
-import sys
-import textwrap
-
-role_colors = {
-    "system": "\033[33m",
-    "user": "\033[36m",
-    "assistant": "\033[32m",
-    "tool": "\033[35m",
-}
-reset = "\033[0m"
-budget = max(1000, int(os.environ.get("MESSAGE_OUTPUT_BUDGET_CHARS", "12000")))
-artifact_path = os.environ.get("MESSAGE_ARTIFACT_PATH", "")
-
-def format_content(content, indent=2):
-    if content is None:
-        content = ""
-    content = str(content)
-    prefix = " " * indent
-    return textwrap.fill(content, width=100, initial_indent=prefix, subsequent_indent=prefix)
-
-payload = sys.stdin.read().strip()
-if not payload:
-    print("(no messages found)")
-    sys.exit(0)
-
-rows = json.loads(payload)
-if not rows:
-    print("(no messages found)")
-    sys.exit(0)
-
-rendered_blocks = []
-artifact_lines = []
-truncated_rows = 0
-for row in rows:
-    seq = row.get("seq_in_session")
-    role = str(row.get("role") or "unknown")
-    ts = row.get("ts") or ""
-    artifact_content = str(row.get("artifact_content_text") or row.get("content_text") or "")
-    content = str(row.get("content_text") or "")
-    content_chars = len(artifact_content)
-    preview_part_count = max(1, int(row.get("preview_part_count") or 1))
-    truncated_part_count = max(0, int(row.get("truncated_part_count") or 0))
-    is_truncated = bool(row.get("is_truncated"))
-    color = role_colors.get(role, "")
-    if seq is None:
-        header = f"\n{color}{role.upper()}{reset} {ts}"
-    else:
-        header = f"\n{color}[{seq}] {role.upper()}{reset} {ts}"
-    suffix = ""
-    artifact_suffix = ""
-    if is_truncated:
-        truncated_rows += 1
-        if preview_part_count > 1:
-            suffix = (
-                f"\n  [per-part tail preview: {preview_part_count} parts, "
-                f"{truncated_part_count} truncated, {content_chars} chars total]"
-            )
-            artifact_suffix += (
-                f"\n  [preview used per-part tail excerpts across {preview_part_count} parts; "
-                f"full extracted content retained]"
-            )
-        else:
-            visible_chars = len(content) - 3 if content.startswith("...") else len(content)
-            suffix = f"\n  [tail preview truncated: showing last {min(content_chars, visible_chars)} of {content_chars} chars]"
-            artifact_suffix += f"\n  [tail preview truncated from {content_chars} chars]"
-    block = f"{header}\n{format_content(content)}{suffix}"
-    rendered_blocks.append(block)
-    artifact_lines.append(f"{header}\n{format_content(artifact_content)}{artifact_suffix}")
-
-total_chars = 0
-printed = 0
-for block in rendered_blocks:
-    projected = total_chars + len(block)
-    if printed > 0 and projected > budget:
-        break
-    print(block)
-    total_chars = projected
-    printed += 1
-
-omitted = len(rendered_blocks) - printed
-artifact_needed = bool(artifact_path) and (
-    omitted > 0 or truncated_rows > 0 or len(rendered_blocks) > 8
-)
-if artifact_needed:
-    with open(artifact_path, "w", encoding="utf-8") as handle:
-        handle.write("Spotlight Query message artifact\n")
-        handle.write(f"rows={len(rendered_blocks)} truncated_rows={truncated_rows}\n")
-        handle.write("\n".join(artifact_lines))
-        handle.write("\n")
-
-if omitted > 0:
-    print(f"\nOutput clipped after {printed} rows to stay within {budget} chars.")
-    if artifact_path:
-        print(f"Artifact: {artifact_path}")
-elif artifact_needed:
-    print(f"\nArtifact: {artifact_path}")
-    '
-}
-
-query_session_last_messages() {
-    local session_id="$1"
-    local limit="${2:-8}"
-    local escaped_session_id
-    local artifact_path
-    escaped_session_id="$(escape_sql_literal "${session_id}")"
-
-    if ! [[ "${limit}" =~ ^[0-9]+$ ]]; then
-        echo "Limit must be numeric"
-        exit 1
-    fi
-
-    if has_indexed_db; then
-        artifact_path="$(make_artifact_path "session-last-$(sanitize_artifact_label "${session_id}")" "txt")"
-        echo "📊 Last ${limit} User/Assistant Messages (safe preview): ${session_id}"
-        echo "================================================================"
-        run_duckdb_json_sql "
-        WITH latest_call AS (
-            SELECT
-                trace_id,
-                turn_id,
-                request_id,
-                start_ms,
-                input_messages_raw,
-                output_messages_raw
-            FROM model_calls
-            WHERE session_id = '${escaped_session_id}'
-            ORDER BY start_ms DESC
-            LIMIT 1
-        ),
-        input_messages AS (
-            SELECT
-                CAST(message.key AS BIGINT) + 1 AS seq_in_session,
-                LOWER(COALESCE(
-                    json_extract_string(message.value, '$.role'),
-                    json_extract_string(message.value, '$.message.role'),
-                    'unknown'
-                )) AS role,
-                message.value AS message_json,
-                to_timestamp((SELECT start_ms FROM latest_call) / 1000.0) AS ts,
-                (SELECT turn_id FROM latest_call) AS turn_id,
-                (SELECT trace_id FROM latest_call) AS trace_id,
-                COALESCE(
-                    NULLIF(json_extract_string(message.value, '$.text'), ''),
-                    NULLIF(json_extract_string(message.value, '$.message.content'), ''),
-                    NULLIF(json_extract_string(message.value, '$.content'), ''),
-                    ''
-                ) AS fallback_text
-            FROM latest_call,
-                 json_each(COALESCE(input_messages_raw, '[]'::JSON)) message
-        ),
-        input_parts AS (
-            SELECT
-                raw_parts.seq_in_session,
-                raw_parts.part_index,
-                raw_parts.part_text,
-                CASE
-                    WHEN length(raw_parts.part_text) > ${MESSAGE_PART_PREVIEW_CHARS}
-                        THEN '...' || right(raw_parts.part_text, ${MESSAGE_PART_PREVIEW_CHARS})
-                    ELSE raw_parts.part_text
-                END AS part_preview_text,
-                length(raw_parts.part_text) > ${MESSAGE_PART_PREVIEW_CHARS} AS part_is_truncated
-            FROM (
-                SELECT
-                    input_messages.seq_in_session,
-                    CAST(part.key AS BIGINT) AS part_index,
-                    LOWER(COALESCE(json_extract_string(part.value, '$.type'), '')) AS part_type,
-                    part_text
-                FROM input_messages
-                LEFT JOIN json_each(
-                    CASE
-                        WHEN json_type(json_extract(input_messages.message_json, '$.parts')) = 'ARRAY'
-                            THEN json_extract(input_messages.message_json, '$.parts')
-                        WHEN json_type(json_extract(input_messages.message_json, '$.message.parts')) = 'ARRAY'
-                            THEN json_extract(input_messages.message_json, '$.message.parts')
-                        WHEN json_type(json_extract(input_messages.message_json, '$.content')) = 'ARRAY'
-                            THEN json_extract(input_messages.message_json, '$.content')
-                        WHEN json_type(json_extract(input_messages.message_json, '$.message.content')) = 'ARRAY'
-                            THEN json_extract(input_messages.message_json, '$.message.content')
-                        ELSE '[]'::JSON
-                    END
-                ) part ON TRUE
-                CROSS JOIN (
-                    SELECT COALESCE(
-                        NULLIF(json_extract_string(part.value, '$.text'), ''),
-                        NULLIF(json_extract_string(part.value, '$.content'), ''),
-                        ''
-                    ) AS part_text
-                ) extracted
-            ) raw_parts
-            WHERE raw_parts.part_type NOT IN ('thinking', 'signature', 'tool_result')
-              AND raw_parts.part_text <> ''
-        ),
-        input_expanded AS (
-            SELECT
-                input_messages.seq_in_session,
-                input_messages.role,
-                COALESCE(
-                    NULLIF(string_agg(input_parts.part_text, '\n' ORDER BY input_parts.part_index), ''),
-                    input_messages.fallback_text
-                ) AS content_text,
-                COALESCE(
-                    NULLIF(string_agg(input_parts.part_preview_text, '\n...\n' ORDER BY input_parts.part_index), ''),
-                    CASE
-                        WHEN length(input_messages.fallback_text) > ${MESSAGE_PART_PREVIEW_CHARS}
-                            THEN '...' || right(input_messages.fallback_text, ${MESSAGE_PART_PREVIEW_CHARS})
-                        ELSE input_messages.fallback_text
-                    END
-                ) AS preview_text,
-                CASE
-                    WHEN COUNT(input_parts.part_text) > 0 THEN COUNT(input_parts.part_text)
-                    WHEN input_messages.fallback_text <> '' THEN 1
-                    ELSE 0
-                END AS preview_part_count,
-                CASE
-                    WHEN COUNT(input_parts.part_text) > 0 THEN SUM(CASE WHEN input_parts.part_is_truncated THEN 1 ELSE 0 END)
-                    WHEN length(input_messages.fallback_text) > ${MESSAGE_PART_PREVIEW_CHARS} THEN 1
-                    ELSE 0
-                END AS truncated_part_count,
-                input_messages.ts,
-                input_messages.turn_id,
-                input_messages.trace_id
-            FROM input_messages
-            LEFT JOIN input_parts
-              ON input_parts.seq_in_session = input_messages.seq_in_session
-            GROUP BY
-                input_messages.seq_in_session,
-                input_messages.role,
-                input_messages.fallback_text,
-                input_messages.ts,
-                input_messages.turn_id,
-                input_messages.trace_id
-        ),
-        output_messages AS (
-            SELECT
-                (SELECT COALESCE(MAX(seq_in_session), 0) FROM input_expanded) + CAST(message.key AS BIGINT) + 1 AS seq_in_session,
-                LOWER(COALESCE(
-                    json_extract_string(message.value, '$.role'),
-                    json_extract_string(message.value, '$.message.role'),
-                    'assistant'
-                )) AS role,
-                message.value AS message_json,
-                to_timestamp((SELECT start_ms FROM latest_call) / 1000.0) AS ts,
-                (SELECT turn_id FROM latest_call) AS turn_id,
-                (SELECT trace_id FROM latest_call) AS trace_id,
-                COALESCE(
-                    NULLIF(json_extract_string(message.value, '$.text'), ''),
-                    NULLIF(json_extract_string(message.value, '$.message.content'), ''),
-                    NULLIF(json_extract_string(message.value, '$.content'), ''),
-                    ''
-                ) AS fallback_text
-            FROM latest_call,
-                 json_each(COALESCE(output_messages_raw, '[]'::JSON)) message
-        ),
-        output_parts AS (
-            SELECT
-                raw_parts.seq_in_session,
-                raw_parts.part_index,
-                raw_parts.part_text,
-                CASE
-                    WHEN length(raw_parts.part_text) > ${MESSAGE_PART_PREVIEW_CHARS}
-                        THEN '...' || right(raw_parts.part_text, ${MESSAGE_PART_PREVIEW_CHARS})
-                    ELSE raw_parts.part_text
-                END AS part_preview_text,
-                length(raw_parts.part_text) > ${MESSAGE_PART_PREVIEW_CHARS} AS part_is_truncated
-            FROM (
-                SELECT
-                    output_messages.seq_in_session,
-                    CAST(part.key AS BIGINT) AS part_index,
-                    LOWER(COALESCE(json_extract_string(part.value, '$.type'), '')) AS part_type,
-                    part_text
-                FROM output_messages
-                LEFT JOIN json_each(
-                    CASE
-                        WHEN json_type(json_extract(output_messages.message_json, '$.parts')) = 'ARRAY'
-                            THEN json_extract(output_messages.message_json, '$.parts')
-                        WHEN json_type(json_extract(output_messages.message_json, '$.message.parts')) = 'ARRAY'
-                            THEN json_extract(output_messages.message_json, '$.message.parts')
-                        WHEN json_type(json_extract(output_messages.message_json, '$.content')) = 'ARRAY'
-                            THEN json_extract(output_messages.message_json, '$.content')
-                        WHEN json_type(json_extract(output_messages.message_json, '$.message.content')) = 'ARRAY'
-                            THEN json_extract(output_messages.message_json, '$.message.content')
-                        ELSE '[]'::JSON
-                    END
-                ) part ON TRUE
-                CROSS JOIN (
-                    SELECT COALESCE(
-                        NULLIF(json_extract_string(part.value, '$.text'), ''),
-                        NULLIF(json_extract_string(part.value, '$.content'), ''),
-                        ''
-                    ) AS part_text
-                ) extracted
-            ) raw_parts
-            WHERE raw_parts.part_type NOT IN ('thinking', 'signature', 'tool_result')
-              AND raw_parts.part_text <> ''
-        ),
-        output_expanded AS (
-            SELECT
-                output_messages.seq_in_session,
-                output_messages.role,
-                COALESCE(
-                    NULLIF(string_agg(output_parts.part_text, '\n' ORDER BY output_parts.part_index), ''),
-                    output_messages.fallback_text
-                ) AS content_text,
-                COALESCE(
-                    NULLIF(string_agg(output_parts.part_preview_text, '\n...\n' ORDER BY output_parts.part_index), ''),
-                    CASE
-                        WHEN length(output_messages.fallback_text) > ${MESSAGE_PART_PREVIEW_CHARS}
-                            THEN '...' || right(output_messages.fallback_text, ${MESSAGE_PART_PREVIEW_CHARS})
-                        ELSE output_messages.fallback_text
-                    END
-                ) AS preview_text,
-                CASE
-                    WHEN COUNT(output_parts.part_text) > 0 THEN COUNT(output_parts.part_text)
-                    WHEN output_messages.fallback_text <> '' THEN 1
-                    ELSE 0
-                END AS preview_part_count,
-                CASE
-                    WHEN COUNT(output_parts.part_text) > 0 THEN SUM(CASE WHEN output_parts.part_is_truncated THEN 1 ELSE 0 END)
-                    WHEN length(output_messages.fallback_text) > ${MESSAGE_PART_PREVIEW_CHARS} THEN 1
-                    ELSE 0
-                END AS truncated_part_count,
-                output_messages.ts,
-                output_messages.turn_id,
-                output_messages.trace_id
-            FROM output_messages
-            LEFT JOIN output_parts
-              ON output_parts.seq_in_session = output_messages.seq_in_session
-            GROUP BY
-                output_messages.seq_in_session,
-                output_messages.role,
-                output_messages.fallback_text,
-                output_messages.ts,
-                output_messages.turn_id,
-                output_messages.trace_id
-        ),
-        expanded AS (
-            SELECT * FROM input_expanded
-            UNION ALL
-            SELECT * FROM output_expanded
-        ),
-        filtered AS (
-            SELECT *
-            FROM expanded
-            WHERE role IN ('user', 'assistant')
-              AND content_text <> ''
-        ),
-        last_rows AS (
-            SELECT *
-            FROM filtered
-            ORDER BY seq_in_session DESC
-            LIMIT ${limit}
-        )
-        SELECT
-            seq_in_session,
-            role,
-            preview_text AS content_text,
-            content_text AS artifact_content_text,
-            length(content_text) AS content_chars,
-            truncated_part_count > 0 AS is_truncated,
-            preview_part_count,
-            truncated_part_count,
-            ts,
-            turn_id,
-            trace_id
-        FROM last_rows
-        ORDER BY seq_in_session ASC;
-        " | MESSAGE_PREVIEW_CHARS="${MESSAGE_PREVIEW_CHARS}" MESSAGE_OUTPUT_BUDGET_CHARS="${MESSAGE_OUTPUT_BUDGET_CHARS}" MESSAGE_ARTIFACT_PATH="${artifact_path}" format_messages_rows
-        return
-    fi
-
-    echo "Indexed analytics DB not found; falling back to trace parsing."
-    query_session_messages "${session_id}" "${limit}"
-}
-
-query_session_tools() {
-    local session_id="$1"
-    local escaped_session_id
-    escaped_session_id="$(escape_sql_literal "${session_id}")"
-
-    if has_indexed_db; then
-        echo "🔧 Session Tools: ${session_id}"
-        echo "=============================="
-        run_duckdb_sql "
-        SELECT
-            call_ts,
-            tool_name,
-            status,
-            ROUND(COALESCE(duration_ms, 0), 2) AS duration_ms,
-            LEFT(COALESCE(arguments_text, ''), 200) AS arguments_preview,
-            LEFT(COALESCE(result_text, ''), 200) AS result_preview,
-            COALESCE(error_message, '') AS error_message
-        FROM tool_calls
-        WHERE session_id = '${escaped_session_id}'
-        ORDER BY call_ts;
-        "
-        return
-    fi
-
-    echo "Indexed analytics DB not found; tool-level session history is unavailable without index DB."
-    exit 1
-}
-
-query_session_summary_fast() {
-    local session_id="$1"
-    local escaped_session_id
-    escaped_session_id="$(escape_sql_literal "${session_id}")"
-
-    if has_indexed_db; then
-        echo "📊 Session Summary: ${session_id}"
-        echo "==============================="
-        run_duckdb_sql "
-        SELECT
-            session_id,
-            COALESCE(agent_id, '') AS agent_id,
-            COALESCE(agent_version, '') AS agent_version,
-            COALESCE(engine, '') AS engine,
-            COALESCE(status, '') AS status,
-            started_at,
-            ended_at,
-            total_turns,
-            total_requests,
-            ROUND(COALESCE(total_cost_usd, 0), 6) AS total_cost_usd,
-            COALESCE(total_tokens, 0) AS total_tokens
-        FROM sessions
-        WHERE session_id = '${escaped_session_id}'
-        LIMIT 1;
-        "
-        return
-    fi
-
-    query_session "${session_id}"
-}
-
-query_latest_session_fast() {
-    if has_indexed_db; then
-        echo "📊 Latest Session"
-        echo "================"
-        run_duckdb_sql "
-        SELECT
-            session_id,
-            COALESCE(agent_id, '') AS agent_id,
-            COALESCE(agent_version, '') AS agent_version,
-            COALESCE(engine, '') AS engine,
-            COALESCE(status, '') AS status,
-            started_at,
-            ended_at,
-            total_turns,
-            total_requests,
-            ROUND(COALESCE(total_cost_usd, 0), 6) AS total_cost_usd,
-            COALESCE(total_tokens, 0) AS total_tokens
-        FROM sessions
-        ORDER BY ended_at DESC NULLS LAST, started_at DESC NULLS LAST
-        LIMIT 1;
-        "
-        return
-    fi
-
-    query_latest_session
-}
-
-query_request_fast() {
-    local request_id="$1"
-    local escaped_request_id
-    escaped_request_id="$(escape_sql_literal "${request_id}")"
-
-    if has_indexed_db; then
-        echo "📊 Request: ${request_id}"
-        echo "========================="
-        run_duckdb_sql "
-        SELECT
-            model,
-            ROUND(COALESCE(total_cost_usd, 0), 6) AS cost,
-            prompt_tokens AS input_tokens,
-            completion_tokens AS output_tokens,
-            ROUND(COALESCE(duration_ms, 0), 2) AS latency_ms,
-            COALESCE(turn_id, '') AS turn_id,
-            to_timestamp(start_ms / 1000.0) AS timestamp
-        FROM model_calls
-        WHERE request_id = '${escaped_request_id}'
-        ORDER BY start_ms;
-        "
-        return
-    fi
-
-    query_request "${request_id}"
-}
-
-query_session_fast() {
-    local session_id="$1"
-    local escaped_session_id
-    escaped_session_id="$(escape_sql_literal "${session_id}")"
-
-    if has_indexed_db; then
-        echo "📊 Session: ${session_id}"
-        echo "========================="
-        run_duckdb_sql "
-        SELECT
-            model,
-            ROUND(COALESCE(total_cost_usd, 0), 6) as cost,
-            prompt_tokens as input_tokens,
-            completion_tokens as output_tokens,
-            ROUND(COALESCE(duration_ms, 0), 2) as latency_ms,
-            COALESCE(request_id, '') as request_id,
-            to_timestamp(start_ms / 1000.0) as timestamp
-        FROM model_calls
-        WHERE session_id = '${escaped_session_id}'
-        ORDER BY start_ms;
-        "
-        return
-    fi
-
-    query_session "${session_id}"
-}
-
-query_cost_by_session_fast() {
-    if has_indexed_db; then
-        echo "📊 Cost by Session"
-        echo "=================="
-        run_duckdb_sql "
-        SELECT
-            session_id,
-            ROUND(COALESCE(total_cost_usd, 0), 6) as total_cost,
-            COALESCE(total_tokens, 0) as total_tokens,
-            total_requests as requests,
-            total_turns as turns,
-            started_at,
-            ended_at
-        FROM sessions
-        ORDER BY total_cost DESC
-        LIMIT 20;
-        "
-        return
-    fi
-
-    query_cost_by_session
-}
-
-query_cost_by_model_fast() {
-    if has_indexed_db; then
-        echo "📊 Cost by Model"
-        echo "================"
-        run_duckdb_sql "
-        SELECT
-            COALESCE(model, '(unknown)') as model,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) as total_cost,
-            SUM(COALESCE(prompt_tokens, 0)) as input_tokens,
-            SUM(COALESCE(completion_tokens, 0)) as output_tokens,
-            COUNT(*) as requests,
-            ROUND(AVG(COALESCE(duration_ms, 0)), 2) as avg_latency_ms
-        FROM model_calls
-        GROUP BY model
-        ORDER BY total_cost DESC;
-        "
-        return
-    fi
-
-    query_cost_by_model
-}
-
-query_cost_by_pack_fast() {
-    if has_indexed_db; then
-        echo "📊 Cost by Agent"
-        echo "================"
-        run_duckdb_sql "
-        SELECT
-            COALESCE(agent_id, '(no agent)') AS agent,
-            COALESCE(agent_version, '?') AS version,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS total_cost,
-            SUM(COALESCE(prompt_tokens, 0)) AS input_tokens,
-            SUM(COALESCE(completion_tokens, 0)) AS output_tokens,
-            COUNT(*) AS requests
-        FROM model_calls
-        GROUP BY agent_id, agent_version
-        ORDER BY total_cost DESC;
-        "
-        return
-    fi
-
-    query_cost_by_pack
-}
-
-query_cost_by_engine_fast() {
-    if has_indexed_db; then
-        echo "📊 Cost by Engine"
-        echo "================="
-        run_duckdb_sql "
-        SELECT
-            COALESCE(engine, '(unknown)') AS engine,
-            COALESCE(model, '(unknown)') AS model,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS total_cost,
-            COUNT(*) AS requests,
-            SUM(COALESCE(prompt_tokens, 0)) AS input_tokens,
-            SUM(COALESCE(completion_tokens, 0)) AS output_tokens
-        FROM model_calls
-        GROUP BY engine, model
-        ORDER BY total_cost DESC;
-        "
-        return
-    fi
-
-    query_cost_by_engine
-}
-
-query_cost_by_source_fast() {
-    if has_indexed_db; then
-        echo "📊 Cost by Source"
-        echo "================="
-        run_duckdb_sql "
-        SELECT
-            COALESCE(source, '(unknown)') AS source,
-            COALESCE(model, '(unknown)') AS model,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS total_cost,
-            COUNT(*) AS requests,
-            SUM(COALESCE(prompt_tokens, 0)) AS input_tokens,
-            SUM(COALESCE(completion_tokens, 0)) AS output_tokens
-        FROM model_calls
-        GROUP BY source, model
-        ORDER BY total_cost DESC;
-        "
-        return
-    fi
-
-    query_cost_by_source
-}
-
-query_total_cost_fast() {
-    if has_indexed_db; then
-        echo "📊 Total Cost Summary"
-        echo "===================="
-        run_duckdb_sql "
-        SELECT
-            ROUND(COALESCE(SUM(total_cost_usd), 0), 6) as total_cost,
-            COALESCE(SUM(prompt_tokens), 0) as total_input_tokens,
-            COALESCE(SUM(completion_tokens), 0) as total_output_tokens,
-            COUNT(*) as total_requests,
-            ROUND(AVG(COALESCE(duration_ms, 0)), 2) as avg_latency_ms
-        FROM model_calls;
-        "
-        return
-    fi
-
-    query_total_cost
-}
-
-query_cost_per_request_fast() {
-    local session_id="${1:-}"
-    if has_indexed_db; then
-        local where_clause="WHERE request_id IS NOT NULL"
-        echo "📊 Cost per Request"
-        echo "==================="
-        if [[ -n "${session_id}" ]]; then
-            where_clause="WHERE session_id = '$(escape_sql_literal "${session_id}")' AND request_id IS NOT NULL"
-            echo "   Session: ${session_id}"
-        fi
-        run_duckdb_sql "
-        SELECT
-            request_id,
-            COUNT(*) AS llm_calls,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS request_cost,
-            SUM(COALESCE(prompt_tokens, 0)) AS input_tokens,
-            SUM(COALESCE(completion_tokens, 0)) AS output_tokens,
-            ROUND(SUM(COALESCE(duration_ms, 0)), 0) AS total_latency_ms,
-            MIN(to_timestamp(start_ms / 1000.0)) AS started_at
-        FROM model_calls
-        ${where_clause}
-        GROUP BY request_id
-        ORDER BY MIN(start_ms);
-        "
-        return
-    fi
-
-    query_cost_per_request "${session_id}"
-}
-
-query_session_timeline_fast() {
-    local session_id="$1"
-    local escaped_session_id
-    escaped_session_id="$(escape_sql_literal "${session_id}")"
-
-    if has_indexed_db; then
-        echo "📊 Session Timeline: ${session_id}"
-        run_duckdb_sql "
-        SELECT
-            to_timestamp(start_ms / 1000.0) AS event_ts,
-            'llm_call' AS event_type,
-            '' AS role,
-            COALESCE(model, '') AS model,
-            '' AS tool_name,
-            LEFT(COALESCE(request_id, ''), 220) AS detail,
-            ROUND(COALESCE(total_cost_usd, 0), 6) AS cost,
-            COALESCE(total_tokens, 0) AS total_tokens,
-            COALESCE(status, '') AS status
-        FROM model_calls
-        WHERE session_id = '${escaped_session_id}'
-
-        UNION ALL
-
-        SELECT
-            call_ts AS event_ts,
-            'tool_call' AS event_type,
-            '' AS role,
-            '' AS model,
-            COALESCE(tool_name, '') AS tool_name,
-            LEFT(COALESCE(arguments_text, ''), 220) AS detail,
-            0.0 AS cost,
-            0 AS total_tokens,
-            COALESCE(status, '') AS status
-        FROM tool_calls
-        WHERE session_id = '${escaped_session_id}'
-
-        ORDER BY event_ts;
-        "
-        return
-    fi
-
-    query_session_timeline "${session_id}"
-}
-
-query_compare_versions_fast() {
-    local agent_name="$1"
-    local escaped_agent_name
-    escaped_agent_name="$(escape_sql_literal "${agent_name}")"
-
-    if has_indexed_db; then
-        echo "📊 Compare Versions: ${agent_name}"
-        echo "===================================="
-        run_duckdb_sql "
-        SELECT
-            agent_version AS version,
-            COUNT(DISTINCT session_id) AS sessions,
-            ROUND(AVG(session_cost), 4) AS avg_cost_per_session,
-            ROUND(AVG(session_tokens), 0) AS avg_tokens_per_session,
-            ROUND(AVG(session_latency), 0) AS avg_latency_ms,
-            ROUND(AVG(requests_per_session), 1) AS avg_llm_calls
-        FROM (
-            SELECT
-                agent_version,
-                session_id,
-                SUM(COALESCE(total_cost_usd, 0)) AS session_cost,
-                SUM(COALESCE(prompt_tokens, 0) + COALESCE(completion_tokens, 0)) AS session_tokens,
-                SUM(COALESCE(duration_ms, 0)) AS session_latency,
-                COUNT(*) AS requests_per_session
-            FROM model_calls
-            WHERE agent_id = '${escaped_agent_name}'
-            GROUP BY agent_version, session_id
-        )
-        GROUP BY agent_version
-        ORDER BY agent_version DESC;
-        "
-        return
-    fi
-
-    query_compare_versions "${agent_name}"
-}
-
-query_top_sessions_fast() {
-    local agent_name="$1"
-    local since_ms="${2:-86400000}"
-    local escaped_agent_name
-    escaped_agent_name="$(escape_sql_literal "${agent_name}")"
-
-    if has_indexed_db; then
-        echo "📊 Top Sessions: ${agent_name}"
-        echo "==============================="
-        run_duckdb_sql "
-        WITH recent AS (
-            SELECT *
-            FROM model_calls
-            WHERE agent_id = '${escaped_agent_name}'
-              AND start_ms > (EXTRACT(EPOCH FROM NOW()) * 1000 - ${since_ms})
-        ),
-        target AS (
-            SELECT * FROM recent
-            UNION ALL
-            SELECT *
-            FROM model_calls
-            WHERE agent_id = '${escaped_agent_name}'
-              AND NOT EXISTS (SELECT 1 FROM recent)
-        )
-        SELECT
-            session_id,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS total_cost,
-            SUM(COALESCE(prompt_tokens, 0)) AS input_tokens,
-            SUM(COALESCE(completion_tokens, 0)) AS output_tokens,
-            COUNT(*) AS llm_calls,
-            COUNT(DISTINCT request_id) AS requests,
-            ROUND(AVG(COALESCE(duration_ms, 0)), 0) AS avg_latency_ms,
-            MIN(to_timestamp(start_ms / 1000.0)) AS started_at
-        FROM target
-        GROUP BY session_id
-        ORDER BY total_cost DESC
-        LIMIT 10;
-        "
-        return
-    fi
-
-    query_top_sessions "${agent_name}" "${since_ms}"
-}
-
-query_agent_kpis_daily() {
-    if has_indexed_db; then
-        echo "📊 Agent KPIs Daily"
-        run_duckdb_sql "
-        SELECT *
-        FROM agent_kpis_daily
-        ORDER BY day DESC, total_cost_usd DESC
-        LIMIT 50;
-        "
-        return
-    fi
-
-    echo "Indexed analytics DB not found; daily KPI view unavailable without index DB."
-    exit 1
-}
-
-query_training_examples() {
-    echo "training_examples view has been retired in this refactor."
-    echo "Use --session-last for message snapshots and --session-timeline for model/tool event chronology."
-    exit 1
-}
-
-query_recent_messages() {
-    local limit="${1:-20}"
-    if ! [[ "${limit}" =~ ^[0-9]+$ ]]; then
-        echo "Limit must be numeric"
-        exit 1
-    fi
-
-    if has_indexed_db; then
-        echo "📊 Recent Sessions (message snapshot source)"
-        echo "==========================================="
-        run_duckdb_sql "
-        SELECT
-            session_id,
-            to_timestamp(MAX(start_ms) / 1000.0) AS latest_call_ts,
-            COUNT(*) AS model_calls,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS total_cost,
-            SUM(COALESCE(total_tokens, 0)) AS total_tokens
-        FROM model_calls
-        GROUP BY session_id
-        ORDER BY latest_call_ts DESC
-        LIMIT ${limit};
-        "
-        return
-    fi
-
-    echo "Indexed analytics DB not found; recent session query unavailable without index DB."
-    exit 1
-}
-
-query_last_session_messages() {
-    local limit="${1:-8}"
-    if ! [[ "${limit}" =~ ^[0-9]+$ ]]; then
-        echo "Limit must be numeric"
-        exit 1
-    fi
-
-    if has_indexed_db; then
-        local latest_session
-        latest_session="$(${DUCKDB} -readonly "${INDEX_DB_PATH}" -csv -c "
-            SELECT session_id
-            FROM sessions
-            ORDER BY ended_at DESC NULLS LAST, started_at DESC NULLS LAST
-            LIMIT 1;
-        " | tail -n 1)"
-
-        if [[ -z "${latest_session}" ]]; then
-            echo "No sessions found in indexed DB."
-            exit 0
-        fi
-
-        query_session_last_messages "${latest_session}" "${limit}"
-        return
-    fi
-
-    local latest_session
-    latest_session="$(${DUCKDB} -csv -c "
-        ${BASE_QUERY},
-        extracted AS (${EXTRACT_ATTRS})
-        SELECT session_id
-        FROM extracted
-        WHERE session_id IS NOT NULL
-        ORDER BY start_ms DESC
-        LIMIT 1;
-    " | tail -n 1)"
-    if [[ -z "${latest_session}" ]]; then
-        echo "No sessions found in traces."
-        exit 0
-    fi
-    query_session_messages "${latest_session}" "${limit}"
-}
-
-query_session_debug() {
-    local session_id="$1"
-    local escaped_session_id
-    escaped_session_id="$(escape_sql_literal "${session_id}")"
-
-    echo "📊 Session Debug: ${session_id}"
-    echo "=============================="
-
-    if has_indexed_db; then
-        echo ""
-        echo "Summary"
-        echo "-------"
-        run_duckdb_sql "
-        SELECT
-            session_id,
-            COALESCE(agent_id, '') AS agent_id,
-            COALESCE(agent_version, '') AS agent_version,
-            COALESCE(engine, '') AS engine,
-            COALESCE(status, '') AS status,
-            started_at,
-            ended_at,
-            total_turns,
-            total_requests,
-            ROUND(COALESCE(total_cost_usd, 0), 6) AS total_cost_usd,
-            COALESCE(total_tokens, 0) AS total_tokens
-        FROM sessions
-        WHERE session_id = '${escaped_session_id}'
-        LIMIT 1;
-        "
-
-        echo ""
-        echo "Recent Requests"
-        echo "---------------"
-        run_duckdb_sql "
-        SELECT
-            COALESCE(request_id, '') AS request_id,
-            COUNT(*) AS llm_calls,
-            ROUND(SUM(COALESCE(total_cost_usd, 0)), 6) AS total_cost_usd,
-            SUM(COALESCE(prompt_tokens, 0) + COALESCE(completion_tokens, 0)) AS total_tokens,
-            SUM(CASE WHEN lower(COALESCE(status, '')) IN ('error', 'failed', 'failure') THEN 1 ELSE 0 END) AS error_calls,
-            MAX(to_timestamp(start_ms / 1000.0)) AS latest_call_ts
-        FROM model_calls
-        WHERE session_id = '${escaped_session_id}'
-        GROUP BY request_id
-        ORDER BY latest_call_ts DESC
-        LIMIT ${SESSION_DEBUG_REQUEST_LIMIT};
-        "
-
-        if has_indexed_table "tool_calls"; then
-            echo ""
-            echo "Tool Signals"
-            echo "------------"
-            run_duckdb_sql "
-            SELECT
-                COALESCE(request_id, '') AS request_id,
-                COALESCE(tool_name, '') AS tool_name,
-                COUNT(*) AS calls,
-                SUM(CASE WHEN lower(COALESCE(status, '')) IN ('error', 'failed', 'failure') THEN 1 ELSE 0 END) AS error_calls,
-                ROUND(AVG(COALESCE(duration_ms, 0)), 2) AS avg_duration_ms,
-                MAX(call_ts) AS latest_call_ts
-            FROM tool_calls
-            WHERE session_id = '${escaped_session_id}'
-            GROUP BY request_id, tool_name
-            ORDER BY error_calls DESC, calls DESC, latest_call_ts DESC
-            LIMIT ${SESSION_DEBUG_TOOL_LIMIT};
-            "
-        fi
-
-        echo ""
-        query_session_last_messages "${session_id}" 4
-        echo ""
-        echo "Next"
-        echo "----"
-        echo "Use --request <request-id> for one request, --session-tools ${session_id} for tool details, or --session-timeline ${session_id} for chronology."
-        return
-    fi
-
-    echo ""
-    echo "Indexed analytics DB not found; using trace/session-file fallback."
-    echo ""
-    query_session "${session_id}"
-    echo ""
-    if [[ -f "${SESSIONS_DIR}/${session_id}.jsonl" ]]; then
-        query_tool_loops "${session_id}"
-        echo ""
-    fi
-    query_session_messages "${session_id}" 4
-    echo ""
-    echo "Next"
-    echo "----"
-    echo "Use --session ${session_id} for all LLM calls or --session-timeline ${session_id} for chronology."
-}
-
-# Base query to parse OTEL JSONL format
-# Note: OTEL Collector file exporter writes one JSON object per line
-BASE_QUERY="
-WITH raw_spans AS (
-    SELECT
-        unnest(resourceSpans) as rs
-    FROM read_json('${TRACES_DIR}/*.jsonl',
-                   format='newline_delimited',
-                   ignore_errors=true)
-),
-spans AS (
-    SELECT
-        unnest(rs.scopeSpans) as ss
-    FROM raw_spans
-),
-flat_spans AS (
-    SELECT
-        unnest(ss.spans) as span
-    FROM spans
-),
-parsed AS (
-    SELECT
-        span.traceId as trace_id,
-        span.spanId as span_id,
-        span.name as span_name,
-        span.startTimeUnixNano::BIGINT / 1000000 as start_ms,
-        span.endTimeUnixNano::BIGINT / 1000000 as end_ms,
-        (span.endTimeUnixNano::BIGINT - span.startTimeUnixNano::BIGINT) / 1000000 as duration_ms,
-        json_extract(to_json(span), '$.attributes') as attrs_json
-    FROM flat_spans
-),
-span_filter AS (
-    SELECT
-        trace_id,
-        span_name,
-        duration_ms,
-        start_ms,
-        attrs_json
-    FROM parsed
-    WHERE span_name = 'Received Proxy Server Request'
-       OR EXISTS (
-           SELECT 1
-           FROM json_each(coalesce(attrs_json, '[]'::JSON)) as attr
-           WHERE json_extract_string(attr.value, '$.key') = 'gen_ai.cost.total_cost'
-       )
-),
-attrs AS (
-    SELECT
-        trace_id,
-        span_name,
-        duration_ms,
-        start_ms,
-        json_extract_string(value, '$.key') as attr_key,
-        json_extract_string(value, '$.value.stringValue') as attr_string,
-        json_extract_string(value, '$.value.intValue') as attr_int,
-        json_extract(value, '$.value.doubleValue') as attr_double
-    FROM span_filter,
-         json_each(coalesce(attrs_json, '[]'::JSON))
-)
-"
-
-# Extract LLM attributes from OTEL span attributes
-# OTEL attributes are stored as array of {key, value} objects
-# Canonical metadata source: metadata.requester_custom_headers (x-litellm-metadata-*)
-# Enriched with: session_id, user_id, project_id, agent_id, agent_version, source, engine, request_id
-EXTRACT_ATTRS="
-WITH span_rows AS (
-    SELECT
-        trace_id,
-        span_name,
-        duration_ms,
-        start_ms,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-session-id'': ''([^'']+)''', 1
-        ), '') as session_id,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-user-id'': ''([^'']+)''', 1
-        ), '') as user_id,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-project-id'': ''([^'']+)''', 1
-        ), '') as project_id,
-        max(CASE WHEN attr_key IN ('gen_ai.request.model', 'gen_ai.response.model', 'model') THEN attr_string END) as model,
-        max(CASE WHEN attr_key = 'gen_ai.cost.total_cost' THEN CAST(attr_double AS DOUBLE) END) as cost,
-        max(CASE WHEN attr_key = 'gen_ai.usage.input_tokens' THEN CAST(attr_int AS BIGINT) END) as input_tokens,
-        max(CASE WHEN attr_key = 'gen_ai.usage.output_tokens' THEN CAST(attr_int AS BIGINT) END) as output_tokens,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-agent-id'': ''([^'']+)''', 1
-        ), '') as agent_id,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-agent-version'': ''([^'']+)''', 1
-        ), '') as agent_version,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-source'': ''([^'']+)''', 1
-        ), '') as source,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-engine'': ''([^'']+)''', 1
-        ), '') as engine,
-        NULLIF(regexp_extract(
-            max(CASE WHEN attr_key = 'metadata.requester_custom_headers' THEN attr_string END),
-            'x-litellm-metadata-request-id'': ''([^'']+)''', 1
-        ), '') as request_id
-    FROM attrs
-    GROUP BY trace_id, span_name, duration_ms, start_ms
-),
-deduped AS (
-    SELECT DISTINCT ON (trace_id)
-        trace_id,
-        span_name,
-        duration_ms,
-        start_ms,
-        session_id,
-        user_id,
-        project_id,
-        model,
-        cost,
-        input_tokens,
-        output_tokens,
-        agent_id,
-        agent_version,
-        source,
-        engine,
-        request_id
-    FROM span_rows
-    ORDER BY
-        trace_id,
-        COALESCE(cost, 0) DESC,
-        CASE
-            WHEN span_name = 'raw_gen_ai_request' THEN 0
-            WHEN span_name = 'litellm_request' THEN 1
-            ELSE 2
-        END,
-        start_ms DESC
-)
-SELECT * FROM deduped
-"
-
-# ============================================================================
-# Query functions
-# ============================================================================
-
-query_total_cost() {
-    check_traces
-    echo "📊 Total Cost Summary"
-    echo "===================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(SUM(cost), 0) as total_cost,
-        COALESCE(SUM(input_tokens), 0) as total_input_tokens,
-        COALESCE(SUM(output_tokens), 0) as total_output_tokens,
-        COUNT(*) as total_requests,
-        ROUND(AVG(duration_ms), 0) as avg_latency_ms
-    FROM extracted;
-    "
-}
-
-query_cost_by_session() {
-    check_traces
-    echo "📊 Cost by Session"
-    echo "=================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(session_id, '(no session)') as session_id,
-        ROUND(COALESCE(SUM(cost), 0), 6) as total_cost,
-        COALESCE(SUM(input_tokens), 0) as input_tokens,
-        COALESCE(SUM(output_tokens), 0) as output_tokens,
-        COUNT(*) as requests,
-        ROUND(AVG(duration_ms), 0) as avg_latency_ms
-    FROM extracted
-    GROUP BY session_id
-    ORDER BY total_cost DESC
-    LIMIT 20;
-    "
-}
-
-query_cost_by_model() {
-    check_traces
-    echo "📊 Cost by Model"
-    echo "================"
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(model, '(unknown)') as model,
-        ROUND(COALESCE(SUM(cost), 0), 6) as total_cost,
-        COALESCE(SUM(input_tokens), 0) as input_tokens,
-        COALESCE(SUM(output_tokens), 0) as output_tokens,
-        COUNT(*) as requests,
-        ROUND(AVG(duration_ms), 0) as avg_latency_ms
-    FROM extracted
-    GROUP BY model
-    ORDER BY total_cost DESC;
-    "
-}
-
-query_cost_by_pack() {
-    check_traces
-    echo "📊 Cost by Agent"
-    echo "================"
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(agent_id, '(no agent)') as agent,
-        COALESCE(agent_version, '?') as version,
-        ROUND(COALESCE(SUM(cost), 0), 6) as total_cost,
-        COALESCE(SUM(input_tokens), 0) as input_tokens,
-        COALESCE(SUM(output_tokens), 0) as output_tokens,
-        COUNT(*) as requests
-    FROM extracted
-    GROUP BY agent_id, agent_version
-    ORDER BY total_cost DESC;
-    "
-}
-
-query_cost_by_engine() {
-    check_traces
-    echo "📊 Cost by Engine"
-    echo "================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(engine, '(unknown)') as engine,
-        model,
-        ROUND(SUM(cost), 6) as total_cost,
-        COUNT(*) as requests,
-        ROUND(AVG(duration_ms), 0) as avg_latency_ms
-    FROM extracted
-    GROUP BY engine, model
-    ORDER BY total_cost DESC;
-    "
-}
-
-query_cost_by_source() {
-    check_traces
-    echo "📊 Cost by Source Framework"
-    echo "=========================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(source, '(unknown)') as framework,
-        ROUND(SUM(cost), 6) as total_cost,
-        COUNT(DISTINCT session_id) as sessions,
-        COUNT(*) as requests,
-        ROUND(AVG(cost), 6) as avg_cost_per_request
-    FROM extracted
-    GROUP BY source
-    ORDER BY total_cost DESC;
-    "
-}
-
-query_cost_per_request() {
-    local session_id="${1:-}"
-    check_traces
-    echo "📊 Cost per Request"
-    echo "==================="
-    local where_clause=""
-    if [[ -n "${session_id}" ]]; then
-        where_clause="WHERE session_id = '${session_id}' AND request_id IS NOT NULL"
-        echo "   Session: ${session_id}"
-    else
-        where_clause="WHERE request_id IS NOT NULL"
-    fi
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        request_id,
-        COUNT(*) as llm_calls,
-        ROUND(COALESCE(SUM(cost), 0), 6) as request_cost,
-        COALESCE(SUM(input_tokens), 0) as input_tokens,
-        COALESCE(SUM(output_tokens), 0) as output_tokens,
-        ROUND(COALESCE(SUM(duration_ms), 0), 0) as total_latency_ms,
-        MIN(to_timestamp(start_ms / 1000)) as started_at
-    FROM extracted
-    ${where_clause}
-    GROUP BY request_id
-    ORDER BY MIN(start_ms);
-    "
-}
-
-query_session() {
-    local session_id="$1"
-    check_traces
-    echo "📊 Session: ${session_id}"
-    echo "========================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        model,
-        ROUND(cost, 6) as cost,
-        input_tokens,
-        output_tokens,
-        duration_ms as latency_ms,
-        COALESCE(request_id, '') as request_id,
-        to_timestamp(start_ms / 1000) as timestamp
-    FROM extracted
-    WHERE session_id = '${session_id}'
-    ORDER BY start_ms;
-    "
-}
-
-query_request() {
-    local request_id="$1"
-    check_traces
-    echo "📊 Request: ${request_id}"
-    echo "========================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        model,
-        ROUND(cost, 6) as cost,
-        input_tokens,
-        output_tokens,
-        duration_ms as latency_ms,
-        to_timestamp(start_ms / 1000) as timestamp
-    FROM extracted
-    WHERE request_id = '${request_id}'
-    ORDER BY start_ms;
-    "
-}
-
-query_session_messages() {
-    local session_id="$1"
-    local limit="${2:-${TRACE_EVENT_PREVIEW_LIMIT}}"
-    local artifact_path
-    check_traces
-    if ! [[ "${limit}" =~ ^[0-9]+$ ]]; then
-        echo "Limit must be numeric"
-        exit 1
-    fi
-    artifact_path="$(make_artifact_path "session-trace-$(sanitize_artifact_label "${session_id}")" "txt")"
-    echo "📊 Session Messages (trace parse, safe preview): ${session_id}"
-    echo "================================================"
-    python3 - "${TRACES_DIR}" "${session_id}" "${limit}" "${MESSAGE_PREVIEW_CHARS}" "${MESSAGE_OUTPUT_BUDGET_CHARS}" "${artifact_path}" <<'PY'
-import hashlib
-import json
-import os
-import pathlib
-import re
-import sys
-import textwrap
-from datetime import datetime, timezone
-
-traces_dir = pathlib.Path(sys.argv[1])
-target_session = sys.argv[2]
-limit = max(1, int(sys.argv[3]))
-preview_chars = max(80, int(sys.argv[4]))
-output_budget = max(1000, int(sys.argv[5]))
-artifact_path = sys.argv[6]
-
-session_patterns = [
-    re.compile(r"x-litellm-metadata-session-id'?:\s*'([^']+)'"),
-    re.compile(r'"x-litellm-metadata-session-id"\s*:\s*"([^"]+)"'),
-]
-request_patterns = [
-    re.compile(r"x-litellm-metadata-request-id'?:\s*'([^']+)'"),
-    re.compile(r'"x-litellm-metadata-request-id"\s*:\s*"([^"]+)"'),
-]
-
-input_keys = {
-    "gen_ai.input.messages",
-    "llm.None.messages",
-    "llm.openai.messages",
-    "llm.anthropic.messages",
-}
-output_keys = {
-    "gen_ai.output.messages",
-    "llm.openai.choices",
-    "llm.anthropic.completion",
-}
-
-
-def attr_string_value(attr):
-    value = (attr or {}).get("value", {})
-    if "stringValue" in value:
-        return value.get("stringValue")
-    if "intValue" in value:
-        return str(value.get("intValue"))
-    if "doubleValue" in value:
-        return str(value.get("doubleValue"))
-    if "boolValue" in value:
-        return "true" if value.get("boolValue") else "false"
-    return ""
-
-
-def extract_header_value(raw, patterns):
-    if not isinstance(raw, str):
-        return ""
-    for pattern in patterns:
-        match = pattern.search(raw)
-        if match:
-            return match.group(1)
-    return ""
-
-
-def extract_text_parts(msg):
-    if isinstance(msg, str):
-        return [msg]
-    if not isinstance(msg, dict):
-        return [str(msg)]
-
-    if "message" in msg:
-        return extract_text_parts(msg["message"])
-
-    if "choices" in msg and isinstance(msg["choices"], list):
-        collected = []
-        for choice in msg["choices"]:
-            collected.extend(extract_text_parts(choice))
-        return collected
-
-    for key in ("parts", "content"):
-        value = msg.get(key)
-        if isinstance(value, str):
-            return [value]
-        if isinstance(value, list):
-            collected = []
-            for item in value:
-                if isinstance(item, dict):
-                    item_type = item.get("type", "")
-                    if item_type in ("thinking", "signature", "tool_result"):
-                        continue
-                    text = item.get("text", item.get("content", ""))
-                    if text:
-                        collected.append(str(text))
-                        continue
-                    collected.extend(extract_text_parts(item))
-                elif isinstance(item, str):
-                    collected.append(item)
-            if collected:
-                return collected
-
-    text = msg.get("text")
-    if isinstance(text, str) and text:
-        return [text]
-
-    content = msg.get("content")
-    if isinstance(content, str) and content:
-        return [content]
-
-    return [str(msg)]
-
-
-def build_part_tail_preview(parts):
-    source_parts = [str(part) for part in parts if str(part)]
-    if not source_parts:
-        return "", "", 0, 0
-    part_preview_chars = max(80, min(400, preview_chars))
-    preview_parts = []
-    truncated_part_count = 0
-    for part in source_parts:
-        if len(part) > part_preview_chars:
-            preview_parts.append("..." + part[-part_preview_chars:])
-            truncated_part_count += 1
-        else:
-            preview_parts.append(part)
-    return "\n".join(source_parts), "\n...\n".join(preview_parts), len(source_parts), truncated_part_count
-
-
-def format_text(content, indent=4, width=100):
-    if content is None:
-        content = ""
-    content = str(content)
-    prefix = " " * indent
-    return textwrap.fill(content, width=width, initial_indent=prefix, subsequent_indent=prefix)
-
-
-def iter_payload_messages(payload, kind):
-    try:
-        parsed = json.loads(payload)
-    except Exception:
-        parsed = None
-
-    if isinstance(parsed, list):
-        for item in parsed:
-            yield item
-        return
-    if isinstance(parsed, dict) and isinstance(parsed.get("choices"), list):
-        for item in parsed["choices"]:
-            yield item
-        return
-    if parsed is not None:
-        yield parsed
-        return
-    yield payload
-
-
-messages = []
-seen_payloads = set()
-message_seq = 0
-for file_path in sorted(traces_dir.glob("*.jsonl")):
-    try:
-        with file_path.open("r", encoding="utf-8", errors="ignore") as handle:
-            for line in handle:
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    root = json.loads(line)
-                except Exception:
-                    continue
-
-                for resource_span in root.get("resourceSpans", []) or []:
-                    for scope_span in resource_span.get("scopeSpans", []) or []:
-                        for span in scope_span.get("spans", []) or []:
-                            attrs = span.get("attributes", []) or []
-                            headers = ""
-                            model = ""
-                            input_payloads = []
-                            output_payloads = []
-
-                            for attr in attrs:
-                                key = attr.get("key")
-                                value = attr_string_value(attr)
-                                if key == "metadata.requester_custom_headers" and isinstance(value, str):
-                                    headers = value
-                                elif key in ("gen_ai.request.model", "gen_ai.response.model", "model") and value:
-                                    model = str(value)
-                                elif key in input_keys and value:
-                                    input_payloads.append(str(value))
-                                elif key in output_keys and value:
-                                    output_payloads.append(str(value))
-
-                            session_id = extract_header_value(headers, session_patterns)
-                            if session_id != target_session:
-                                continue
-
-                            request_id = extract_header_value(headers, request_patterns)
-                            try:
-                                start_ns = int(span.get("startTimeUnixNano") or 0)
-                            except Exception:
-                                start_ns = 0
-
-                            trace_id = span.get("traceId", "")
-                            timestamp = datetime.fromtimestamp(start_ns / 1_000_000_000, tz=timezone.utc).isoformat() if start_ns else "(unknown)"
-                            for kind, payloads in (("input", input_payloads), ("output", output_payloads)):
-                                for payload in payloads:
-                                    digest = hashlib.sha1(payload.encode("utf-8", errors="ignore")).hexdigest()
-                                    request_key = request_id or trace_id
-                                    dedupe_key = (kind, request_key, digest)
-                                    if dedupe_key in seen_payloads:
-                                        continue
-                                    seen_payloads.add(dedupe_key)
-                                    for raw_message in iter_payload_messages(payload, kind):
-                                        role = "assistant" if kind == "output" else "user"
-                                        if isinstance(raw_message, dict):
-                                            role = str(
-                                                raw_message.get("role")
-                                                or raw_message.get("message", {}).get("role")
-                                                or role
-                                            ).lower()
-                                        content_parts = extract_text_parts(raw_message)
-                                        content, preview, preview_part_count, truncated_part_count = build_part_tail_preview(content_parts)
-                                        if role not in ("user", "assistant") or not content:
-                                            continue
-                                        message_seq += 1
-                                        messages.append(
-                                            {
-                                                "role": role,
-                                                "ts": timestamp,
-                                                "request_id": request_id,
-                                                "model": model or "(unknown)",
-                                                "start_ns": start_ns,
-                                                "seq": message_seq,
-                                                "content_text": content,
-                                                "content_preview": preview,
-                                                "content_chars": len(content),
-                                                "is_truncated": truncated_part_count > 0,
-                                                "preview_part_count": preview_part_count,
-                                                "truncated_part_count": truncated_part_count,
-                                            }
-                                        )
-    except Exception:
-        continue
-
-if not messages:
-    print("(no trace messages found for this session)")
-    raise SystemExit(0)
-
-messages.sort(key=lambda row: (row["start_ns"], row["seq"]))
-selected = messages[-limit:]
-
-def render_row(row, index, full=False):
-    header = (
-        f"\n[{index}] {row['ts']} | {row['role'].upper()} | model={row['model']}"
-        + (f" | request_id={row['request_id']}" if row["request_id"] else "")
-    )
-    body = format_text(row["content_text"] if full else row["content_preview"])
-    suffix = ""
-    if row["is_truncated"] and not full:
-        if row.get("preview_part_count", 1) > 1:
-            suffix = (
-                f"\n    [per-part tail preview: {row['preview_part_count']} parts, "
-                f"{row.get('truncated_part_count', 0)} truncated, {row['content_chars']} chars total]"
-            )
-        else:
-            visible_chars = len(row["content_preview"]) - 3 if row["content_preview"].startswith("...") else len(row["content_preview"])
-            suffix = f"\n    [tail preview truncated: showing last {visible_chars} of {row['content_chars']} chars]"
-    return f"{header}\n{body}{suffix}"
-
-rendered_selected = [render_row(row, idx) for idx, row in enumerate(selected, start=1)]
-artifact_needed = (
-    len(messages) > len(selected)
-    or any(row["is_truncated"] for row in messages)
-)
-if artifact_needed:
-    with open(artifact_path, "w", encoding="utf-8") as handle:
-        handle.write("Spotlight Query trace message artifact\n")
-        handle.write(f"messages={len(messages)} selected={len(selected)}\n")
-        for idx, row in enumerate(messages, start=1):
-            handle.write(render_row(row, idx, full=True))
-            handle.write("\n")
-
-printed = 0
-consumed = 0
-for block in rendered_selected:
-    projected = consumed + len(block)
-    if printed > 0 and projected > output_budget:
-        break
-    print(block)
-    consumed = projected
-    printed += 1
-
-omitted_from_selection = len(rendered_selected) - printed
-if len(messages) > len(selected):
-    print(f"\nShowing last {len(selected)} of {len(messages)} extracted user/assistant messages.")
-if omitted_from_selection > 0:
-    print(f"Output clipped after {printed} rows to stay within {output_budget} chars.")
-if artifact_needed:
-    print(f"Artifact: {artifact_path}")
-PY
-}
-
-query_compare_versions() {
-    local agent_name="$1"
-    check_traces
-    echo "📊 Compare Versions: ${agent_name}"
-    echo "===================================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        agent_version as version,
-        COUNT(DISTINCT session_id) as sessions,
-        ROUND(AVG(session_cost), 4) as avg_cost_per_session,
-        ROUND(AVG(session_tokens), 0) as avg_tokens_per_session,
-        ROUND(AVG(session_latency), 0) as avg_latency_ms,
-        ROUND(AVG(requests_per_session), 1) as avg_llm_calls
-    FROM (
-        SELECT
-            agent_version,
-            session_id,
-            SUM(cost) as session_cost,
-            SUM(COALESCE(input_tokens, 0) + COALESCE(output_tokens, 0)) as session_tokens,
-            SUM(duration_ms) as session_latency,
-            COUNT(*) as requests_per_session
-        FROM extracted
-        WHERE agent_id = '${agent_name}'
-        GROUP BY agent_version, session_id
-    )
-    GROUP BY agent_version
-    ORDER BY agent_version DESC;
-    "
-}
-
-query_top_sessions() {
-    local agent_name="$1"
-    local since_ms="${2:-86400000}"  # default: 24h in ms
-    check_traces
-    echo "📊 Top Sessions: ${agent_name}"
-    echo "==============================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        session_id,
-        ROUND(SUM(cost), 6) as total_cost,
-        COALESCE(SUM(input_tokens), 0) as input_tokens,
-        COALESCE(SUM(output_tokens), 0) as output_tokens,
-        COUNT(*) as llm_calls,
-        COUNT(DISTINCT request_id) as requests,
-        ROUND(AVG(duration_ms), 0) as avg_latency_ms,
-        MIN(to_timestamp(start_ms / 1000)) as started_at
-    FROM extracted
-    WHERE agent_id = '${agent_name}'
-      AND start_ms > (EXTRACT(EPOCH FROM NOW()) * 1000 - ${since_ms})
-    GROUP BY session_id
-    ORDER BY total_cost DESC
-    LIMIT 10;
-    "
-}
-
-query_latency_percentiles() {
-    check_traces
-    echo "📊 Latency Percentiles (by model and agent)"
-    echo "============================================"
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(agent_id, '(default)') as agent,
-        model,
-        COUNT(*) as requests,
-        ROUND(PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY duration_ms), 0) as p50_ms,
-        ROUND(PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY duration_ms), 0) as p95_ms,
-        ROUND(AVG(duration_ms), 0) as avg_ms,
-        MAX(duration_ms) as max_ms
-    FROM extracted
-    GROUP BY agent_id, model
-    ORDER BY p95_ms DESC;
-    "
-}
-
-query_errors() {
-    check_traces
-    echo "📊 Error Rate by Model"
-    echo "======================"
-    echo "(Note: error detection depends on LiteLLM OTEL span attributes)"
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS}),
-    error_traces AS (
-        SELECT DISTINCT trace_id
-        FROM attrs
-        WHERE attr_key IN ('exception.type', 'exception.message')
-           OR (attr_key = 'otel.status_code' AND attr_string = 'ERROR')
-           OR (attr_key = 'http.status_code' AND CAST(attr_int AS INT) >= 400)
-    )
-    SELECT
-        COALESCE(e.model, '(unknown)') as model,
-        COUNT(*) as total_requests,
-        COUNT(er.trace_id) as errors,
-        ROUND(COUNT(er.trace_id)::FLOAT / COUNT(*) * 100, 1) as error_rate_pct
-    FROM extracted e
-    LEFT JOIN error_traces er ON e.trace_id = er.trace_id
-    GROUP BY e.model
-    ORDER BY error_rate_pct DESC;
-    "
-}
-
-query_largest_requests() {
-    local limit="${1:-20}"
-    check_traces
-    echo "📊 Largest Requests by Input Tokens"
-    echo "===================================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(session_id, '') as session_id,
-        COALESCE(request_id, '') as request_id,
-        COALESCE(agent_id, '') as agent,
-        model,
-        input_tokens,
-        output_tokens,
-        ROUND(cost, 6) as cost,
-        duration_ms as latency_ms,
-        to_timestamp(start_ms / 1000) as timestamp
-    FROM extracted
-    WHERE input_tokens IS NOT NULL
-    ORDER BY input_tokens DESC
-    LIMIT ${limit};
-    "
-}
-
-query_problems() {
-    check_traces
-    echo "📊 Problem Sessions (statistical outliers)"
-    echo "==========================================="
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS}),
-    session_summary AS (
-        SELECT
-            session_id,
-            COALESCE(agent_id, '(default)') as agent_id,
-            ROUND(SUM(cost), 6) as total_cost,
-            SUM(COALESCE(input_tokens, 0)) as total_input_tokens,
-            COUNT(*) as llm_calls,
-            COUNT(DISTINCT request_id) as requests,
-            MAX(duration_ms) as max_latency_ms,
-            MIN(to_timestamp(start_ms / 1000)) as started_at
-        FROM extracted
-        GROUP BY session_id, agent_id
-    ),
-    overall_stats AS (
-        SELECT
-            AVG(total_cost) as avg_cost,
-            STDDEV(total_cost) as stddev_cost,
-            AVG(total_input_tokens) as avg_tokens,
-            STDDEV(total_input_tokens) as stddev_tokens
-        FROM session_summary
-        WHERE total_cost > 0
-    )
-    SELECT
-        s.session_id,
-        s.agent_id as agent,
-        s.total_cost,
-        s.total_input_tokens as input_tokens,
-        s.llm_calls,
-        s.requests,
-        s.max_latency_ms,
-        CASE
-            WHEN o.stddev_cost > 0 AND s.total_cost > o.avg_cost + 2 * o.stddev_cost THEN 'COST OUTLIER'
-            WHEN o.stddev_tokens > 0 AND s.total_input_tokens > o.avg_tokens + 2 * o.stddev_tokens THEN 'TOKEN OUTLIER'
-            WHEN s.requests > 0 AND s.llm_calls > s.requests * 5 THEN 'EXCESSIVE LLM CALLS'
-            WHEN s.max_latency_ms > 30000 THEN 'HIGH LATENCY'
-            ELSE '?'
-        END as problem_type,
-        s.started_at
-    FROM session_summary s, overall_stats o
-    WHERE (o.stddev_cost > 0 AND s.total_cost > o.avg_cost + 2 * o.stddev_cost)
-       OR (o.stddev_tokens > 0 AND s.total_input_tokens > o.avg_tokens + 2 * o.stddev_tokens)
-       OR (s.requests > 0 AND s.llm_calls > s.requests * 5)
-       OR s.max_latency_ms > 30000
-    ORDER BY s.total_cost DESC
-    LIMIT 20;
-    "
-}
-
-# ============================================================================
-# Tier 2: Session Event Queries (require Layer 2 session events)
-# Session events live in ${ANALYTICS_DIR}/sessions/<session_id>.jsonl
-# ============================================================================
-SESSIONS_DIR="${ANALYTICS_DIR}/sessions"
-
-check_sessions() {
-    if ! ls "${SESSIONS_DIR}"/*.jsonl &> /dev/null; then
-        echo "No session event files found in ${SESSIONS_DIR}/"
-        echo "Session events are captured when running agents with observability enabled."
-        exit 0
-    fi
-}
-
-query_tool_loops() {
-    local session_id="$1"
-    check_sessions
-    echo "📊 Tool Loop Detection: ${session_id}"
-    echo "======================================"
-    ${DUCKDB} -c "
-    WITH tool_events AS (
-        SELECT
-            session_id,
-            request_id,
-            json_extract_string(to_json(payload), '$.toolName') as tool_name,
-            json_extract_string(to_json(payload), '$.callId') as call_id,
-            timestamp
-        FROM read_json(
-            '${SESSIONS_DIR}/${session_id}.jsonl',
-            format='newline_delimited',
-            ignore_errors=true
-        )
-        WHERE event_type = 'tool_start'
-    ),
-    tool_counts AS (
-        SELECT
-            request_id,
-            tool_name,
-            COUNT(*) as call_count,
-            MIN(timestamp) as first_call,
-            MAX(timestamp) as last_call
-        FROM tool_events
-        GROUP BY request_id, tool_name
-    )
-    SELECT
-        COALESCE(request_id, '(unknown)') as request_id,
-        tool_name,
-        call_count,
-        CASE WHEN call_count > 5 THEN 'POSSIBLE LOOP' ELSE 'ok' END as status,
-        ROUND((last_call - first_call) / 1000.0, 1) as span_seconds
-    FROM tool_counts
-    ORDER BY call_count DESC;
-    "
-}
-
-query_tool_stats() {
-    local session_filter="${1:-}"
-    check_sessions
-    echo "📊 Tool Usage Statistics"
-    echo "========================"
-    local glob_pattern
-    if [[ -n "${session_filter}" ]]; then
-        glob_pattern="${SESSIONS_DIR}/${session_filter}.jsonl"
-        echo "   Session: ${session_filter}"
-    else
-        glob_pattern="${SESSIONS_DIR}/*.jsonl"
-    fi
-    ${DUCKDB} -c "
-    WITH starts AS (
-        SELECT
-            session_id,
-            request_id,
-            json_extract_string(to_json(payload), '$.toolName') as tool_name,
-            json_extract_string(to_json(payload), '$.callId') as call_id,
-            timestamp as start_ts
-        FROM read_json('${glob_pattern}',
-                       format='newline_delimited', ignore_errors=true)
-        WHERE event_type = 'tool_start'
-          AND json_extract_string(to_json(payload), '$.callId') IS NOT NULL
-          AND json_extract_string(to_json(payload), '$.callId') != ''
-    ),
-    ends AS (
-        SELECT
-            session_id,
-            request_id,
-            json_extract_string(to_json(payload), '$.toolName') as tool_name,
-            json_extract_string(to_json(payload), '$.callId') as call_id,
-            timestamp as end_ts,
-            CASE WHEN json_extract_string(to_json(payload), '$.isError') = 'true' THEN 1 ELSE 0 END as is_error
-        FROM read_json('${glob_pattern}',
-                       format='newline_delimited', ignore_errors=true)
-        WHERE event_type = 'tool_end'
-          AND json_extract_string(to_json(payload), '$.callId') IS NOT NULL
-          AND json_extract_string(to_json(payload), '$.callId') != ''
-    ),
-    tool_pairs AS (
-        SELECT
-            s.tool_name,
-            (e.end_ts - s.start_ts) as duration_ms,
-            e.is_error
-        FROM starts s
-        JOIN ends e ON s.call_id = e.call_id AND s.session_id = e.session_id AND s.request_id = e.request_id
-    )
-    SELECT
-        tool_name,
-        COUNT(*) as total_calls,
-        ROUND(AVG(duration_ms), 0) as avg_duration_ms,
-        ROUND(SUM(is_error)::FLOAT / COUNT(*) * 100, 1) as error_rate_pct,
-        MAX(duration_ms) as max_duration_ms
-    FROM tool_pairs
-    GROUP BY tool_name
-    ORDER BY total_calls DESC;
-    "
-}
-
-query_session_timeline() {
-    local session_id="$1"
-    check_traces
-    echo "📊 Session Timeline: ${session_id}"
-    echo "==================================="
-    echo "(unified LLM calls + tool events)"
-    # Check if session events exist for this session
-    local has_events=false
-    if [[ -f "${SESSIONS_DIR}/${session_id}.jsonl" ]]; then
-        has_events=true
-    fi
-
-    if [[ "${has_events}" == "true" ]]; then
-        ${DUCKDB} -c "
-        ${BASE_QUERY},
-        extracted AS (${EXTRACT_ATTRS}),
-        llm_events AS (
-            SELECT
-                start_ms as timestamp,
-                'llm_call' as event_type,
-                model as detail,
-                ROUND(cost, 6) as cost,
-                input_tokens,
-                output_tokens,
-                duration_ms
-            FROM extracted
-            WHERE session_id = '${session_id}'
-        ),
-        agent_events AS (
-            SELECT
-                timestamp,
-                event_type,
-                COALESCE(
-                    json_extract_string(to_json(payload), '$.toolName'),
-                    event_type
-                ) as detail,
-                NULL::DOUBLE as cost,
-                NULL::BIGINT as input_tokens,
-                NULL::BIGINT as output_tokens,
-                NULL::BIGINT as duration_ms
-            FROM read_json(
-                '${SESSIONS_DIR}/${session_id}.jsonl',
-                format='newline_delimited',
-                ignore_errors=true
-            )
-        )
-        SELECT * FROM (
-            SELECT * FROM llm_events
-            UNION ALL
-            SELECT * FROM agent_events
-        )
-        ORDER BY timestamp;
-        "
-    else
-        # No session events — just show LLM calls
-        ${DUCKDB} -c "
-        ${BASE_QUERY},
-        extracted AS (${EXTRACT_ATTRS})
-        SELECT
-            start_ms as timestamp,
-            'llm_call' as event_type,
-            model as detail,
-            ROUND(cost, 6) as cost,
-            input_tokens,
-            output_tokens,
-            duration_ms
-        FROM extracted
-        WHERE session_id = '${session_id}'
-        ORDER BY start_ms;
-        "
-    fi
-}
-
-query_latest_session() {
-    check_traces
-    echo "📊 Latest Session"
-    echo "================"
-    ${DUCKDB} -c "
-    ${BASE_QUERY},
-    extracted AS (${EXTRACT_ATTRS})
-    SELECT
-        COALESCE(session_id, '(no session)') as session_id,
-        COALESCE(model, '(unknown)') as model,
-        ROUND(COALESCE(cost, 0), 6) as cost,
-        COALESCE(input_tokens, 0) as input_tokens,
-        COALESCE(output_tokens, 0) as output_tokens,
-        duration_ms as latency_ms,
-        COALESCE(agent_id, '') as agent_id,
-        COALESCE(request_id, '') as request_id,
-        to_timestamp(start_ms / 1000) as timestamp
-    FROM extracted
-    ORDER BY start_ms DESC
-    LIMIT 1;
-    "
-}
-
-query_custom() {
-    local sql="$1"
-    check_traces
-
-    # Catch common shell-expansion pitfall:
-    # --sql "${BASE_QUERY}, extracted AS (${EXTRACT_ATTRS}) ..."
-    # If BASE_QUERY/EXTRACT_ATTRS are not defined in the caller shell, this becomes invalid SQL.
-    if [[ "${sql}" == *"extracted AS ()"* ]] || [[ "${sql}" == *"attrs AS ()"* ]]; then
-        echo "Invalid SQL: CTE placeholders were expanded to empty by your shell."
-        echo "Hint: wrap --sql in single quotes, e.g.:"
-        echo "  --sql '\${BASE_QUERY}, extracted AS (\${EXTRACT_ATTRS}) SELECT COUNT(*) FROM extracted'"
-        exit 1
-    fi
-
-    # Support callers that pass placeholders literally (e.g. Python subprocess):
-    #   ${BASE_QUERY}, extracted AS (${EXTRACT_ATTRS}) ...
-    local expanded_sql="${sql//\$\{BASE_QUERY\}/${BASE_QUERY}}"
-    expanded_sql="${expanded_sql//\$\{EXTRACT_ATTRS\}/${EXTRACT_ATTRS}}"
-    expanded_sql="${expanded_sql//\$BASE_QUERY/${BASE_QUERY}}"
-    expanded_sql="${expanded_sql//\$EXTRACT_ATTRS/${EXTRACT_ATTRS}}"
-    run_duckdb_sql "${expanded_sql}"
-}
-
-interactive_shell() {
-    check_traces
-    echo "🦆 DuckDB Interactive Shell"
-    echo "==========================="
-    echo ""
-    if has_indexed_db; then
-        echo "Indexed DB: ${INDEX_DB_PATH}"
-        echo ""
-        echo "Example queries:"
-        echo "  SELECT * FROM sessions ORDER BY ended_at DESC LIMIT 5;"
-        echo "  SELECT session_id, request_id, start_ms FROM model_calls ORDER BY start_ms DESC LIMIT 20;"
-        echo ""
-        ${DUCKDB} -readonly "${INDEX_DB_PATH}"
-    else
-        echo "Trace files: ${TRACES_DIR}/*.jsonl"
-        echo ""
-        echo "Example queries:"
-        echo "  SELECT * FROM read_json('${TRACES_DIR}/*.jsonl') LIMIT 5;"
-        echo ""
-        ${DUCKDB}
-    fi
-}
-
-dump_schema() {
-    if ! has_indexed_db; then
-        echo '{"error": "Indexed analytics DB not found. Schema discovery requires analytics.duckdb."}' | python3 -m json.tool
-        exit 1
-    fi
-
-    INDEX_DB_PATH="${INDEX_DB_PATH}" DUCKDB_BIN="${DUCKDB}" python3 << 'PYTHON_EOF'
-import json
-import subprocess
-import sys
-import os
-
-db_path = os.environ.get('INDEX_DB_PATH', '')
-duckdb_bin = os.environ.get('DUCKDB_BIN', 'duckdb')
-if not db_path:
-    print('{"error": "INDEX_DB_PATH not set"}', file=sys.stderr)
-    sys.exit(1)
-
-def run_query(sql):
-    """Run DuckDB query and return JSON results."""
-    result = subprocess.run(
-        [duckdb_bin, '-readonly', db_path, '-json', '-c', sql],
-        capture_output=True,
-        text=True
-    )
-    if result.returncode != 0:
-        print(f"Error: {result.stderr}", file=sys.stderr)
-        return []
-    try:
-        return json.loads(result.stdout)
-    except json.JSONDecodeError:
-        return []
-
-# Fetch all tables
-tables = run_query("""
-    SELECT table_name
-    FROM information_schema.tables
-    WHERE table_schema = 'main'
-    ORDER BY table_name
-""")
-
-# Fetch all columns with types and indices
-columns = run_query("""
-    SELECT table_name, column_name, data_type
-    FROM information_schema.columns
-    WHERE table_schema = 'main'
-    ORDER BY table_name, ordinal_position
-""")
-
-# Fetch primary keys
-pks = run_query("""
-    SELECT table_name, column_name
-    FROM information_schema.key_column_usage
-    WHERE table_schema = 'main' AND constraint_type = 'PRIMARY KEY'
-    ORDER BY table_name, ordinal_position
-""")
-
-# Fetch foreign keys
-fks = run_query("""
-    SELECT
-        table_name,
-        column_name,
-        constraint_name
-    FROM information_schema.key_column_usage
-    WHERE table_schema = 'main' AND constraint_type = 'FOREIGN KEY'
-    ORDER BY table_name
-""")
-
-# Fetch index info
-indices = run_query("""
-    SELECT table_name, index_name, expressions
-    FROM duckdb_indexes()
-    ORDER BY table_name
-""")
-
-# Build output structure
-pk_set = set((row['table_name'], row['column_name']) for row in pks)
-col_map = {}
-for row in columns:
-    tbl = row['table_name']
-    if tbl not in col_map:
-        col_map[tbl] = []
-    col_map[tbl].append({
-        'name': row['column_name'],
-        'type': row['data_type'],
-        'is_primary_key': (tbl, row['column_name']) in pk_set
-    })
-
-idx_map = {}
-for row in indices:
-    tbl = row['table_name']
-    if tbl not in idx_map:
-        idx_map[tbl] = []
-    idx_map[tbl].append({
-        'name': row['index_name'],
-        'expressions': row['expressions']
-    })
-
-schema = {
-    'tables': [
-        {
-            'name': t['table_name'],
-            'columns': col_map.get(t['table_name'], []),
-            'indices': idx_map.get(t['table_name'], [])
-        }
-        for t in tables
-    ],
-    'relationships': [
-        {
-            'table': fk['table_name'],
-            'column': fk['column_name'],
-            'constraint': fk['constraint_name']
-        }
-        for fk in fks
-    ]
-}
-
-print(json.dumps(schema, indent=2))
-PYTHON_EOF
-}
-
-# Parse --since duration to milliseconds (e.g., 24h, 7d, 1h)
-parse_since() {
-    local since="$1"
-    local num="${since%[hdm]}"
-    local unit="${since: -1}"
-    case "${unit}" in
-        h) echo $(( num * 3600000 )) ;;
-        d) echo $(( num * 86400000 )) ;;
-        m) echo $(( num * 60000 )) ;;
-        *) echo "86400000" ;;  # default 24h
-    esac
-}
-
-# Main
-case "${1:-}" in
-    --cost)
-        query_total_cost_fast
-        ;;
-    --cost-by-session|--sessions)
-        query_cost_by_session_fast
-        ;;
-    --cost-by-model|--models)
-        query_cost_by_model_fast
-        ;;
-    --cost-by-pack|--agents)
-        query_cost_by_pack_fast
-        ;;
-    --cost-by-engine)
-        query_cost_by_engine_fast
-        ;;
-    --cost-by-source)
-        query_cost_by_source_fast
-        ;;
-    --cost-per-request)
-        query_cost_per_request_fast "${2:-}"
-        ;;
-    --session)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session <session-id>"
-            exit 1
-        fi
-        query_session_fast "$2"
-        ;;
-    --session-summary)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session-summary <session-id>"
-            exit 1
-        fi
-        query_session_summary_fast "$2"
-        ;;
-    --session-debug)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session-debug <session-id>"
-            exit 1
-        fi
-        query_session_debug "$2"
-        ;;
-    --session-last)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session-last <session-id> [limit]"
-            exit 1
-        fi
-        query_session_last_messages "$2" "${3:-8}"
-        ;;
-    --session-messages|--messages)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session-messages <session-id>"
-            exit 1
-        fi
-        query_session_last_messages "$2" "${3:-8}"
-        ;;
-    --session-tools)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session-tools <session-id>"
-            exit 1
-        fi
-        query_session_tools "$2"
-        ;;
-    --recent-messages)
-        query_recent_messages "${2:-20}"
-        ;;
-    --last-session-messages)
-        query_last_session_messages "${2:-8}"
-        ;;
-    --request)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --request <request-id>"
-            exit 1
-        fi
-        query_request_fast "$2"
-        ;;
-    --latest-session)
-        query_latest_session_fast
-        ;;
-    --kpis-daily)
-        query_agent_kpis_daily
-        ;;
-    --training-examples)
-        query_training_examples "${2:-20}"
-        ;;
-    --session-timeline)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --session-timeline <session-id>"
-            exit 1
-        fi
-        query_session_timeline_fast "$2"
-        ;;
-    --compare-versions)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --compare-versions <agent-name>"
-            exit 1
-        fi
-        query_compare_versions_fast "$2"
-        ;;
-    --top-sessions)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --top-sessions <agent-name> [--since <duration>]"
-            exit 1
-        fi
-        local_since="86400000"
-        if [[ "${3:-}" == "--since" && -n "${4:-}" ]]; then
-            local_since=$(parse_since "$4")
-        fi
-        query_top_sessions_fast "$2" "${local_since}"
-        ;;
-    --latency-percentiles|--latency)
-        query_latency_percentiles
-        ;;
-    --errors)
-        query_errors
-        ;;
-    --largest-requests)
-        query_largest_requests "${2:-20}"
-        ;;
-    --problems)
-        query_problems
-        ;;
-    --tool-loops)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --tool-loops <session-id>"
-            exit 1
-        fi
-        query_tool_loops "$2"
-        ;;
-    --tool-stats)
-        query_tool_stats "${2:-}"
-        ;;
-    --sql)
-        if [[ -z "${2:-}" ]]; then
-            echo "Usage: $0 --sql \"SELECT ...\""
-            exit 1
-        fi
-        query_custom "$2"
-        ;;
-    --schema)
-        dump_schema
-        ;;
-    --help|-h)
-        echo "Usage: $0 [flag] [args]"
-        echo ""
-        echo "COST ANALYSIS — \"Where is money going?\""
-        echo "  --cost                  Total cost, tokens, request count"
-        echo "  --cost-by-session       Cost per session — find expensive conversations"
-        echo "  --cost-by-model         Cost per model — check tier usage"
-        echo "  --cost-by-pack          Cost per agent — compare agent efficiency"
-        echo "  --cost-by-engine        Cost per engine (claude/codex/etc)"
-        echo "  --cost-by-source        Cost per framework (vscode/cli/api)"
-        echo "  --cost-per-request [id] Cost per user message — find bloated requests"
-        echo ""
-        echo "DEBUGGING — \"What happened in this session/request?\""
-        echo "  --session <id>          All LLM calls in a session"
-        echo "  --session-summary <id>  Session-level totals and metadata"
-        echo "  --session-debug <id>    Compact agent-safe bundle: summary, requests, tools, latest messages"
-        echo "  --session-last <id> [N] Last N conversational user/assistant previews from latest call snapshot"
-        echo "  --session-messages <id> Alias of --session-last"
-        echo "  --session-tools <id>    Tool calls and outcomes in session"
-        echo "  --request <id>          All LLM calls for one user message"
-        echo "  --latest-session        Most recent session summary"
-        echo "  --last-session-messages [N] Last N messages for latest session"
-        echo "  --recent-messages [N]   Most recent sessions by latest call"
-        echo "  --session-timeline <id> Interleaved model/tool timeline"
-        echo "  --kpis-daily            Daily KPI rollup from indexed DB"
-        echo "  --training-examples [N] Retired (prints guidance)"
-        echo ""
-        echo "REGRESSION — \"Did performance change?\""
-        echo "  --compare-versions <agent>  Avg cost/tokens/latency by agent version"
-        echo "  --top-sessions <agent>      Expensive sessions for an agent (last 24h)"
-        echo ""
-        echo "HEALTH — \"What's broken?\""
-        echo "  --problems              Statistical outliers (cost/token/latency spikes)"
-        echo "  --errors                Error rate by model"
-        echo "  --latency-percentiles   p50/p95 latency by model and agent"
-        echo "  --largest-requests [N]  Biggest input token payloads (prompt bloat)"
-        echo "  --tool-loops <id>       Detect repeated tool calls (possible loops)"
-        echo "  --tool-stats [id]       Tool usage frequency and error rates"
-        echo ""
-        echo "DISCOVERY — \"Agent self-service schema learning\""
-        echo "  --schema                All tables, columns, types, and relationships (JSON for agents)"
-        echo "  (no args)               Interactive DuckDB shell"
-        echo ""
-        echo "CUSTOM — \"I need something specific\""
-        echo "  --sql \"SELECT ...\"      Run custom DuckDB SQL"
-        echo ""
-        echo "The --sql flag can use built-in CTEs for complex queries:"
-        echo "  \${BASE_QUERY}   — flattens OTEL JSONL into spans"
-        echo "  \${EXTRACT_ATTRS} — extracts common attributes (cost, model, session, etc)"
-        echo ""
-        echo "Example: scripts/query-analytics.sh --sql \"\${BASE_QUERY}, attrs AS (\${EXTRACT_ATTRS}) SELECT model, SUM(cost) FROM attrs GROUP BY model\""
-        echo ""
-        echo "Options:"
-        echo "  --since <dur>           Time filter for --top-sessions (24h, 7d, 30m)"
-        echo ""
-        echo "Message previews are bounded by default and may spill a fuller preview artifact to ${TMP_DIR}."
-        ;;
-    *)
-        interactive_shell
-        ;;
-esac