Smoke Monkeyv1.2.0
GitHub1.2kGet Started
Debugging
9 min readUpdated: October 2026

How to Debug AI Agent Loops: TypeScript Logging, Tracing & Replay

Technical Review: Smoke Monkey Core Architecture Team
Tested on Node.js 18+ & BunTypeScript 5.x
Quick Answer & Executive Definition

How to Debug AI Agent Loops: TypeScript Logging, Tracing & Replay: Designed as a zero-dependency, open-source TypeScript architecture under the MIT License with native Model Context Protocol (MCP) support and deterministic phase state machines.

Key Architectural Takeaways

Tapping the Agent Event Stream

Every significant action in Smoke Monkey emits a typed event. Subscribe to these events to build custom logging, metrics, or alerting:

debug-agent.tstypescript
import { createAgent } from 'smoke-monkey-harness';


const agent = createAgent({
  provider: 'anthropic',
  model: 'claude-3-7-sonnet',
  workspacePath: process.cwd(),
});


// Log every phase transition
agent.on('phase.changed', (e) => {
  console.log(`[PHASE] ${e.data.from} → ${e.data.to}`);
});


// Log every tool execution with timing
agent.on('tool.executed', (e) => {
  console.log(`[TOOL] ${e.data.toolName} (${e.data.durationMs}ms)`);
  if (e.data.error) console.error('  ERROR:', e.data.error);
});


// Log every model request/response
agent.on('model.response', (e) => {
  console.log(`[MODEL] ${e.data.inputTokens} in → ${e.data.outputTokens} out`);
});


await agent.run('Refactor authentication module');

Common Failure Patterns and How to Fix Them

1. Infinite tool call loops

The agent keeps calling the same tool without making progress. Set maxIterations and subscribe to loop.guard.triggered events to detect this.

2. Context window overflow

Token counts grow until the model truncates early context. Enable context compaction to automatically summarize older messages.

3. Permission gate deadlock

In non-interactive mode, an ask permission fires but nobody is listening. Set autoApprove: true or implement an event listener for permission.requested.

4. Tool output too large

A file read or bash output floods the context. Use the maxBytes option on file tools or pipe large outputs to a summary tool.

Replaying Sessions for Post-Mortem Analysis

Smoke Monkey writes each session as a structured JSON file. You can inspect these files after a run to reconstruct exactly what the agent did:

bash
# Find the latest session
ls -lt ~/.smoke-monkey/sessions/ | head -5

# Pretty-print the session log
cat ~/.smoke-monkey/sessions/<session-id>.json | jq '.events[] | {phase, tool, tokens}'

Enable verbose logging in development

Set DEBUG=smoke-monkey:* in your environment to get full verbose output including raw LLM request/response payloads.

Google Search Questions & Answers

Frequently Asked Questions

Q:How do I set a maximum number of iterations to prevent runaway agents?

Pass maxIterations in the agent config. When the limit is reached, the agent emits a loop.guard.triggered event and halts gracefully without throwing.

Q:Can I trace which specific line of code the agent is editing?

Yes. The tool.executed event for write_file and replace_file_content includes the startLine and endLine of the edit, along with the before/after content diff.

Related Alternatives & Comparisons

vs Cursor Composer

Cursor Composer Agent Alternative: Embeddable Code Editing Engine

Compare
vs Cognition Devin

Open Source Devin Alternative: Build Autonomous Software Engineers in TypeScript

Compare

Build with Smoke Monkey Harness

Zero dependencies. 24 built-in tools. Human-in-the-loop safety. 100% open source under the MIT License.

npm install smoke-monkey-harness