attach

Instructions

Implementation Reference

• src/handlers/debug.ts:26-38 (handler)

  The handler for the 'attach' tool. Extracts the PID from arguments, validates it, then starts a debug session of type 'attach' with the PID.

  case "attach": {
    const pid = Number(args?.pid);
    if (!pid) {
      throw new Error("Process ID is required");
    }
  
    const session = await startDebugSession("attach", pid.toString());
    return {
      content: [{
        type: "text",
        text: `Attached to process ${pid} with session ${session.id}`
      }]
    };

• src/server.ts:399-421 (registration)

  The CallToolRequestSchema handler that routes the 'attach' tool name to handleDebugCommands.

  /**
   * Handler for debug tools
   */
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    // Debug commands
    if (["debug", "attach", "exec", "test", "core", "dap", "replay", "trace"].includes(name)) {
      return handleDebugCommands(name, args);
    }
  
    // Control commands
    if (["setBreakpoint", "removeBreakpoint", "continue", "next", "step", "stepout", "variables", "evaluate"].includes(name)) {
      return handleControlCommands(name, args);
    }
  
    // Configuration commands
    if (["setBackend", "configureLogging", "version"].includes(name)) {
      return handleConfigCommands(name, args);
    }
  
    throw new Error("Unknown tool");
  });

• src/server.ts:85-98 (registration)

  Tool registration with name 'attach', description 'Attach to a running process', and input schema requiring a 'pid' (number).

  {
    name: "attach",
    description: "Attach to a running process",
    inputSchema: {
      type: "object",
      properties: {
        pid: {
          type: "number",
          description: "Process ID to attach to"
        }
      },
      required: ["pid"]
    }
  },

• src/session.ts:35-64 (helper)

  The startDebugSession function that spawns a 'dlv' process with the given type (e.g., 'attach'), target (PID), and arguments.

  export async function startDebugSession(type: string, target: string, args: string[] = []): Promise<DebugSession> {
    const port = await getAvailablePort();
    const id = Math.random().toString(36).substring(7);
    
    const dlvArgs = [
      type,
      "--headless",
      `--listen=:${port}`,
      "--accept-multiclient",
      "--api-version=2",
      target,
      ...args
    ];
  
    const process = spawn("dlv", dlvArgs, {
      stdio: ["pipe", "pipe", "pipe"]
    });
  
    const session: DebugSession = {
      id,
      type,
      target,
      process,
      port,
      breakpoints: new Map()
    };
  
    sessions.set(id, session);
    return session;
  }

• src/types.ts:16-25 (schema)

  The DebugSession interface where the 'type' property can be 'attach' among other debug session types.

  export interface DebugSession {
    id: string;
    type: string; // 'debug' | 'attach' | 'exec' | 'test' | 'core' | 'replay' | 'trace' | 'dap'
    target: string;
    process?: ChildProcess;
    port: number;
    breakpoints: Map<number, Breakpoint>;
    logOutput?: string[];
    backend?: string;
  }