agentic-debugger

Instructions

Implementation Reference

• src/index.ts:275-332 (handler)

  The handler function for the 'read_debug_logs' tool. It checks for an active session, reads raw logs via sessionManager.readLogs(), formats them if 'pretty' is specified, and returns the logs as text content.

  case 'read_debug_logs': {
    if (!sessionManager.isActive()) {
      return {
        content: [{ type: 'text', text: 'No active debug session.' }],
        isError: true,
      };
    }
  
    const format = (args?.format as string) || 'pretty';
    const logs = sessionManager.readLogs();
  
    if (!logs.trim()) {
      return {
        content: [
          {
            type: 'text',
            text: 'No logs collected yet. Make sure to reproduce the bug to trigger the instruments.',
          },
        ],
      };
    }
  
    if (format === 'raw') {
      return {
        content: [{ type: 'text', text: logs }],
      };
    }
  
    // Pretty format
    const entries = logs
      .trim()
      .split('\n')
      .map((line) => {
        try {
          return JSON.parse(line);
        } catch {
          return null;
        }
      })
      .filter(Boolean);
  
    const formatted = entries
      .map((entry, i) => {
        const time = new Date(entry.timestamp).toISOString();
        const data = JSON.stringify(entry.data, null, 2);
        return `[${i + 1}] ${time}\nInstrument: ${entry.id}\nLocation: ${entry.location}\nData:\n${data}`;
      })
      .join('\n\n---\n\n');
  
    return {
      content: [
        {
          type: 'text',
          text: `Debug logs (${entries.length} entries):\n\n${formatted}`,
        },
      ],
    };
  }

• src/index.ts:101-115 (schema)

  The schema definition for the 'read_debug_logs' tool, including input schema with optional 'format' parameter, provided in the ListTools response.

  {
    name: 'read_debug_logs',
    description: 'Read the collected debug logs from the current session.',
    inputSchema: {
      type: 'object',
      properties: {
        format: {
          type: 'string',
          enum: ['raw', 'pretty'],
          description: 'Output format (default: pretty)',
          default: 'pretty',
        },
      },
    },
  },

• src/index.ts:31-126 (registration)

  The registration of all tools including 'read_debug_logs' via the ListToolsRequestSchema handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: 'start_debug_session',
          description: 'Start a debug session. This starts a local HTTP server to receive logs from instrumented code.',
          inputSchema: {
            type: 'object',
            properties: {
              port: {
                type: 'number',
                description: 'Port number for the debug server (default: 9876)',
                default: 9876,
              },
            },
          },
        },
        {
          name: 'stop_debug_session',
          description: 'Stop the current debug session and shut down the log server.',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
        {
          name: 'add_instrument',
          description: 'Add a debug instrument at a specific line in a file. The instrument will log variable values when executed.',
          inputSchema: {
            type: 'object',
            properties: {
              file: {
                type: 'string',
                description: 'Path to the file to instrument (relative to working directory)',
              },
              line: {
                type: 'number',
                description: 'Line number where to insert the instrument (1-indexed)',
              },
              capture: {
                type: 'array',
                items: { type: 'string' },
                description: 'Variable names to capture and log',
                default: [],
              },
            },
            required: ['file', 'line'],
          },
        },
        {
          name: 'remove_instruments',
          description: 'Remove debug instruments from files.',
          inputSchema: {
            type: 'object',
            properties: {
              file: {
                type: 'string',
                description: 'Path to file to remove instruments from. If not specified, removes from all instrumented files.',
              },
            },
          },
        },
        {
          name: 'list_instruments',
          description: 'List all active debug instruments.',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
        {
          name: 'read_debug_logs',
          description: 'Read the collected debug logs from the current session.',
          inputSchema: {
            type: 'object',
            properties: {
              format: {
                type: 'string',
                enum: ['raw', 'pretty'],
                description: 'Output format (default: pretty)',
                default: 'pretty',
              },
            },
          },
        },
        {
          name: 'clear_debug_logs',
          description: 'Clear all collected debug logs.',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
      ],
    };
  });

• src/session.ts:103-113 (helper)

  The SessionManager.readLogs() helper method that reads the raw content from the debug log file.

  readLogs(): string {
    if (!this.session) {
      throw new Error('No active debug session');
    }
  
    if (!existsSync(this.session.logFile)) {
      return '';
    }
  
    return readFileSync(this.session.logFile, 'utf-8');
  }