agentic-debugger

Instructions

Implementation Reference

• src/index.ts:177-207 (handler)

  Main handler for the 'add_instrument' tool. Validates active session, parses input arguments, creates instrument using SessionManager, inserts code using Instrumenter, and returns success message with details.

  case 'add_instrument': {
    if (!sessionManager.isActive() || !instrumenter) {
      return {
        content: [{ type: 'text', text: 'No active debug session. Start one first with start_debug_session.' }],
        isError: true,
      };
    }
  
    const file = args?.file as string;
    const line = args?.line as number;
    const capture = (args?.capture as string[]) || [];
  
    if (!file || !line) {
      return {
        content: [{ type: 'text', text: 'Missing required parameters: file and line' }],
        isError: true,
      };
    }
  
    const instrument = sessionManager.addInstrument({ file, line, capture });
    instrumenter.addInstrument(instrument);
  
    return {
      content: [
        {
          type: 'text',
          text: `Instrument added!\n\nID: ${instrument.id}\nFile: ${instrument.file}\nLine: ${line}\nCapturing: ${capture.length > 0 ? capture.join(', ') : '(no variables)'}\n\nThe instrument will log data when that line is executed.`,
        },
      ],
    };
  }

• src/index.ts:56-79 (registration)

  Tool registration in the listTools response, including name, description, and input schema.

  {
    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'],
    },
  },

• src/index.ts:59-78 (schema)

  Input schema defining parameters for the add_instrument tool: file (string, required), line (number, required), capture (array of strings, optional).

  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'],
  },

• src/session.ts:59-76 (helper)

  SessionManager.addInstrument: Creates Instrument instance with resolved file path, detected language, generates ID, stores in session's instruments Map, returns the instrument.

  addInstrument(options: InstrumentOptions): Instrument {
    if (!this.session) {
      throw new Error('No active debug session');
    }
  
    const language = this.detectLanguage(options.file);
    const instrument: Instrument = {
      id: `dbg-${randomUUID().slice(0, 8)}`,
      file: resolve(this.workingDirectory, options.file),
      line: options.line,
      language,
      capture: options.capture,
      createdAt: Date.now()
    };
  
    this.session.instruments.set(instrument.id, instrument);
    return instrument;
  }

• src/instrumenter.ts:16-35 (helper)

  Instrumenter.addInstrument: Reads target file, validates line number, generates language-specific instrument code, inserts it before the specified line, writes back to file.

  addInstrument(instrument: Instrument): void {
    if (!existsSync(instrument.file)) {
      throw new Error(`File not found: ${instrument.file}`);
    }
  
    const content = readFileSync(instrument.file, 'utf-8');
    const lines = content.split('\n');
  
    if (instrument.line < 1 || instrument.line > lines.length + 1) {
      throw new Error(`Line ${instrument.line} is out of range (file has ${lines.length} lines)`);
    }
  
    const code = this.generateInstrumentCode(instrument);
    const codeLines = code.split('\n');
  
    // Insert at the specified line (1-indexed, so line 5 means insert before index 4)
    lines.splice(instrument.line - 1, 0, ...codeLines);
  
    writeFileSync(instrument.file, lines.join('\n'));
  }