debugging-acai

Debugging acai

Key Principles

1. Never read log files directly - Use tail to view the end of log files
2. Use dynamic-read-session to inspect sessions - Don't read session JSON files directly
3. Correlate errors with sessions - Use sessionId from error logs to find relevant sessions

Log Files

Application Logs

Location: ~/.acai/logs/current.log

Reading logs:

# View last 50 lines
tail -n 50 ~/.acai/logs/current.log

# Follow logs in real-time (in tmux)
tail -f ~/.acai/logs/current.log

# Search for specific session errors
grep "sessionId" ~/.acai/logs/current.log | tail -20

Common Log Patterns

• ERROR level: Application errors that may need investigation
• WARN level: Non-fatal issues that might affect behavior
• agent-error events: Errors emitted by the agent loop

Model Request Timing Telemetry

The agent loop emits one structured JSON log line per model request, correlated by a stable requestId of the form <sessionId>:<iteration>. Each request emits three events (filter on the event field):

• model.request.start — model, provider, iteration, inputTokenEstimate
• model.first_token — ttftMs (time-to-first-token in ms)
• model.request.end — modelResponseMs, ttftMs, inputTokens, outputTokens, outputTokensPerSecond, reasoningTokens, finishReason, retryCount, providerRequestId, and selected providerHeaders (request id, rate-limit, retry-after)

# All timing events for a session
grep '"requestId":"<sessionId>:' ~/.acai/logs/current.log

# Just request-end metrics
grep '"event":"model.request.end"' ~/.acai/logs/current.log | tail -20

Per-turn timing (wallClockMs, modelMs, toolMs) is also persisted in the session file and rolled up in the exit Session Summary (Total/Model/Tools/ Overhead and Tool/Total ratio), so you can see whether a session is dominated by model response time or tool execution.

Session Files

Reading Sessions