Observing Agentforce

/**
 * @description STDM query service for the agentforce-optimize Claude Code skill.
 *              Queries the Session Trace Data Model (STDM) in Data Cloud to retrieve
 *              session traces, conversation turns, messages, and steps for issue analysis.
 *
 *              Deployed once per org by the agentforce-optimize skill (Phase 1 setup).
 *              All public methods accept dataSpaceName so no Data Space is hardcoded.
 *
 * Methods:
 *   findSessions(dataSpaceName, startIso, endIso, maxRows)            → JSON List<SessionSummary>
 *   findSessions(dataSpaceName, startIso, endIso, maxRows, agentName) → JSON List<SessionSummary>
 *   getConversationDetails(dataSpaceName, sessionId)                  → JSON ConversationData
 *   getMultipleConversationDetails(dataSpaceName, sessionIds)         → JSON List<ConversationData>
 *   getLlmStepDetails(dataSpaceName, stepIds)                         → JSON List<LlmStepDetail>
 *   getMomentInsights(dataSpaceName, sessionIds)                      → JSON List<SessionInsights>
 *   getAggregatedMetrics(dataSpaceName, startIso, endIso, maxRows, agentName) → JSON AggregatedMetrics
 *   runObservabilityQuery(List<ObservabilityInput>)                         → List<ObservabilityOutput> (@InvocableMethod)
 */
public with sharing class AgentforceOptimizeService {

    // =========================================================================
    // Output wrappers
    // =========================================================================

    /** Lightweight session record returned by findSessions(). */
    public class SessionSummary {
        public String  session_id;
        public String  start_time;
        public String  end_time;
        public String  channel;
        public Long    duration_ms;
        /** How the session ended: e.g. USER_ENDED, AGENT_ENDED (null = in progress or not recorded) */
        public String  end_type;
    }

    /** A single user/agent message within a turn. */
    public class MessageData {
        public String message_id;
        /** 'Input' (user) or 'Output' (agent) — raw STDM value */
        public String message_type;
        public String text;
        public String sent_at;
    }

    /**
     * A single internal step within a turn.
     * All issue-detection fields are included:
     *   - error          → non-null means ACTION_STEP failure (P1)
     *   - pre_vars / post_vars → null delta means variable not captured (P2)
     *   - duration_ms > 10 000 → slow action (P3)
     *   - generation_id  → non-null on LLM_STEP; use getLlmStepDetails() to get the prompt
     */
    public class StepData {
        public String step_id;
        /** TOPIC_STEP | LLM_STEP | ACTION_STEP | SESSION_END | TRUST_GUARDRAILS_STEP */
        public String step_type;
        public String name;
        public String start_time;
        public String end_time;
        public Long   duration_ms;
        /** Raw input to the step (JSON for ACTION_STEP; Python dict string for LLM_STEP) */
        public String input;
        /** Raw output from the step (JSON for ACTION_STEP; Python dict string for LLM_STEP) */
        public String output;
        /** Non-null indicates the step threw an error (only ACTION_STEP counts toward action_error_count) */
        public String error;
        /** Variable snapshot before this step (null when NOT_SET) */
        public String pre_vars;
        /** Variable snapshot after this step (null when NOT_SET) */
        public String post_vars;
        /** GenAiGeneration ID — non-null on LLM_STEP; pass to getLlmStepDetails() for full prompt/response */
        public String generation_id;
        /** GenAiGatewayRequest ID — non-null on LLM_STEP; links to raw gateway request */
        public String gateway_request_id;
    }

    /**
     * One conversational turn (AiAgentInteraction of type TURN).
     * Contains all messages and steps for that turn.
     */
    public class TurnData {
        public String in