Agent Trace Debugger

Parse and analyze LibrAgent agent session trace files (.trace.json).

Trace File Location

Trace files are typically stored in:

• ~/.libragent/traces/<session_id>.trace.json
• Session-specific directories under the app data folder

Analysis Workflow

1. Load Trace File

import { readFileSync } from 'fs';
const trace = JSON.parse(readFileSync('session.trace.json', 'utf-8'));

2. Extract Tool Call Sequence

const toolCalls = trace.messages
  .filter((m) => m.role === 'assistant' && m.tool_calls)
  .flatMap((m) => m.tool_calls);

3. Correlate with Backend Events

Match trace tool calls with agent:event payloads:

• agent:thinking - LLM reasoning phase
• agent:tool_start - Tool execution start
• agent:tool_end - Tool execution complete
• agent:error - Error during execution

4. Identify Workflow Phases

LibrAgent uses Think-Act-Observe loop:

• Think: LLM generates reasoning and tool calls
• Act: Backend executes tools via MCPServiceProxy
• Observe: Backend adds results to conversation, loop continues

5. Detect Issues

• Failed tool calls without retry
• Long-running tool executions
• Missing tool results in conversation
• Cross-session state leakage (check session IDs)

Key Patterns to Look For

{
  "session_id": "uuid-here",
  "messages": [
    {
      "role": "user",
      "content": "Task description"
    },
    {
      "role": "assistant",
      "content": "Reasoning...",
      "tool_calls": [
        {
          "id": "call_123",
          "function": {
            "name": "planning_create_task",
            "arguments": "{\"title\": \"Task\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_123",
      "content": "Task created"
    }
  ]
}

Integration with Other Tools

• extract-log-debug skill: Extract matching log entries for the same session
• trace-analyzer skill: Deep analysis of trace file structure
• sqlite-analyzer skill: Verify database state matches trace expectations