session-investigator

The Session Investigator skill is an essential diagnostic utility for developers and power users of the fast-agent framework. It provides a structured methodology to inspect, aggregate, and correlate data stored within the .fast-agent/sessions directory. By parsing session.json metadata and history_*.json message files, it enables users to reconstruct conversation flows, trace tool call linkages, and quantify latency across LLM interactions and external MCP server calls. This skill is particularly useful for identifying why a complex multi-turn task failed, debugging recursive tool call loops, or correlating sub-agent traces back to the primary session context.

• Perform deep-dive analysis on session history JSON files to identify specific message roles, stop reasons, and content structures.

• Execute automated jq-based queries to calculate LLM call statistics, including total duration, average response latency, and min/max execution times.

• Correlate assistant tool calls with subsequent user tool results to verify data integrity and diagnose orphaned or failed tool executions.

• Generate session timelines and message rate metrics to visualize interaction flow and identifying potential bottlenecks in agent performance.

• Specifically inspect sub-agent invocation patterns and timing for calls prefixed with agent__ to optimize complex workflow orchestrations.

• Provide common failure pattern detection, specifically for unanswered tool calls where the history chain is broken between assistant requests and expected tool results.

• The skill assumes access to the local .fast-agent filesystem structure where sessions are stored in the YYMMDDHHMM-<random> format.

• Users should have basic familiarity with jq command-line processing to fully leverage the provided scripts for log manipulation and metric extraction.

• It is highly recommended to use this tool when sessions end with non-descriptive errors, such as unexpected turn terminations or API timeouts during tool execution.

• Always refer to the session.json file first to verify the correct history files (previous vs. current) associated with the session ID before running analysis scripts.

• Ideal for use within the fast-agent development lifecycle, particularly when testing new MCP server integrations or tuning agent system prompts for improved reliability and reduced tool loop frequency.